View Source

h1. Current state

* Redesigned on Nov 14-15: Entity, EntityAPI, SearchAPI made interfaces; added support for "shortcut" fields for Search
* Main classes: Backend Factory, EntityAPI, Entity, SearchAPI
* EntityAPI provides basic entity operations: add, edit, delete, load (by URI)
* SearchAPI provides search capabilities (only FullTextSearch for now)
* There is an example: SearchExample.java in the examples package
* Note. The other example was subsumed by RForms and was deleted

h2. Building it

* svn access: [https://svn.ontotext.com/svn/researchspace/trunk/entity-api]
* needs maven to be built; also uses parent pom in ../pom.xml
* needs access to Ontotext/BigOwlim and Aduna repositories, contact Mitac if there are problems building it
* currently the search returns the single MuseumObject in the database, w/o checking the search string
* to run it, you need to unzip the repository in resources folder (resources/susana.zip). Then use bin/example-search:
{code:title=Repository installation|borderStyle=solid}
$ cd your-loc-of-entity-api/entity-api
$ cd resources
$ unzip susana
$ cd ..
$ bin/example-search
{code}


h2. SearchAPI example
{code:title=SearchExample.java|borderStyle=solid}
BackendFactory bf = BackendFactory.getInstance(new File(RSConstants.REPOSITORY));
SearchAPI sa = bf.getSearchAPI();

String query = "Susanna"; //"Batcheba";
Iterator<Entity> it = sa.fullTextSearch(query);
while (it.hasNext()) {
Entity e = it.next();
System.out.println(
e.getUri() + "\t" +
e.getLabel() + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.E55_Type)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.Title)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.Artist)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.Place)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.SupportMaterial)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.Technique)) + "\t" +
sa.getFirstLabel(e.getShortcutField(Entity.Shortcut.CreationDate))
);
} //while
{code}

*Note*. The above example needs the folder RSConstants.REPOSITORY (currently "resources/repositories/susana" to be copied under the current directory")

h1. Definition

Create a light-weight integration API on top of OWLIM/Sesame API that talks in terms of Entities, attributes and relations instead of RDF statements. If possible create a simplified domain ontology that maps to CRM and allow the UI to talk in terms of this ontology, while transparently converting to CRM at the back end.
{jira:RS-37|server=Ontotext Jira}

h2. Basic level

The API should define the following:
* data model: Entities, attributes, relations
* basic operations: insert, update, delete
* Entity lookup (could be moved to the SearchAPI)

h2. Transformation level

Additionally the API should define:
* domain ontology (DO)
* mapping between DO and CRM
* transformation between simplified schema (DO) and CRM, e.g. Painting("Susana") - createdBy - Person("Rembrandt") should be expanded to create a creation Event, AttributeAssignment and (TBD)Version

h2. Search level

* a SearchAPI that uses EntityAPI data model
* structured search
* TBD. Combined FTS+SemanticSearch based on the analysis of the user query

h2. Discussions, Design, Impl. notes

h3. Similar Entity APIs in other Ontotext project (KIM, World KB, ANAM)

* data model based on Sesame data model or java.net.URI + strings
* entity creation only
* use of Aliases (separate Alias object, w/ source, language and other attributes). Each Entity has one or more Aliases, one of each is the main alias (hasAlias; hasMainAlias)
* autocommit mode (the created entities are saved instantly)
* no search APIs

In RS we need more:
* update/delete for both Entities and its attributes/relations
* searches
* transformations
* maybe separate commit


h3. Data model


h4. class Entity

* Class, ID, Label (e.g. Painting, rs:Painting_01234, "Suzana")
* maybe: attrs, rels
* new Entity(Class, URI, Label) - creates an Entity in the KB
* addAttr(URI name, Object val)
* addRel(URI name, URI val)

h4. Class EntityAPI

* new EntityAPI(userData: URI, UserOptions (such as language), AccessRights)
* //createEntity(Entity)
* ?getEntity(URI)
* ?loadEntity(URI)
* deleteEntity(URI)
* autoinc(className)

h4. mapping complex attributes (transformation)

* E - createdBy - User
* model E - ?hasEvent - Creation(Event) - author - Person

* forward request: ea.getEntity(URI).addRel("createdBy", personURI)
* impl: E.addRel("createdBy", personURI)
*- Entity creation = new Entity("Creation", "Creation_" * autoinc("Creation"), null)
*- creation.addRel("author", personURI)
*- E.addRel("hasEvent", creation)

* backward request: ea.loadEntity(URI)
* impl: E.loadRel("createdBy")
*- URI creationURI = E.getRelURI("hasEvent", "Creation")
*- Entity creation = ea.loadEntity(creationURI)
*- URI userURI = creation.getRelURI("author", "User")
*- return ea.loadEntity(userURI)

* update request:
* impl: E.updateRel("createdBy", userURI)
*- URI creationURI = E.getRelURI("hasEvent", "Creation")
*- ea.deleteEntity(creationURI) // Or could use versions
*- Entity creation = new Entity("Creation", "Creation_" * autoinc("Creation"), null)
*- creation.addRel("author", userURI)
*- E.addRel("hasEvent", creation)

* delete request:
* impl: ea.deleteEntity(E)
*- URI creationURI = E.getRelURI("hasEvent", "Creation")
*- ea.deleteEntity(creationURI)
*- ea.deleteEntity(E)

* search processing (structured, full-text):

h3. Open questions

* whether the "save" should happen in EA or Entity (directly)
* metamodel

h3. Misc

* when the UI says "User X said that Person_Rembrandt created Painting_Susana"
* message: "createdBy", "Painting", "Person"
* the backend should do 3 things
*# model of createdBy to be expanded
*# AttributeAssignment for the current user
*# new Version of createdBy
* tie it up as
AttributeAssignment = Version (user, ?number, datetime)

h3. Attribute as an Object


h4. Example

Document - title - string
vs
Document - hasAttribute - Attribute(class) - rdf:type A (name=title, value=string)

h4. Rationale

* easier to make relations (e.g. attach a comment to an instance),
Versions, etc.

h3. Domain Ontology

* Document
* content
* Annotation
* Comment
* Version
* author
* createdOn
* createdBy
* Person
* User
* ?Artist
* ?Painting (or parent class, ArtObject)
* Image
* partOf
* ?Attribute