thinkmap.datasource
Interface IEntityHandler

All Known Implementing Classes:
BinaryStreamWriter, FilterEntityHandler, Message, StreamWriter

public interface IEntityHandler

IEntityHandler is the interface for transmitting data between a thinkmap and a datasource in the form of discrete messages. It is used for requests as well as responses. The grammar of a message is as follows:

MESSAGE: (beginMessage (ENTITY*|ENTITYMD*|ENTITYID*) endMessage)
ENTITY: (beginEntity ENTITYID property* RELATEDLIST? endEntity)
ENTITYID: (beginId idKey* endId)
RELATEDLIST: (beginRelatedList (RELATED) endRelatedList)
RELATED: (beginRelatedEntity (ENTITYID|ENTITY) endRelatedEntity)
ENTITYMD: (beginEntityMD ENTITYIDMD (propertyMD*|property*) endEntityMD)
ENTITYIDMD: (beginId idKeyMD* endId)

In addition, a message can be "annotated" at any point with an attribute. The attribute will apply to whatever is currently being sent. An attribute can be attached to

In practice, there are very few attributes and they're either applied to the message or to an Entity.

An entity type's position in the type hierarchy is defined by its metadata, and the entity itself is matched against this heirarchy based on the its type. For example, to send the entity DIRECTOR:22262, a metadata request must first have been recieved:

beginMessage(METADATA_REQUEST); beginEntityMD(NODE); beginId("DIRECTOR"); idKeyMD(Integer.class); endId(); endEntityMD(); endMessage();

Once this has been recieved, the following message can be properly understood:

beginMessage(ENTITY_REQUEST); beginEntity("DIRECTOR"); beginId("DIRECTOR"); idKey(new Integer(22262)); endId(); // send properties here with property(name, val); endEntity(); endMessage();

Thinkmap will always begin with a metadata request to establish the heirarchy of entity types. Any entities that will ever be sent by a datasource must be described in the response to a metadata request.

Version:
$Revision: 1.8 $

Field Summary
static int ADD_REQUEST
          Add a new entity.
static String ATTR_CACHE_REVISION
          An attribute for version numbers of things in caches
static int DELETE_REQUEST
          Delete an entity.
static String EDGE
          The entity type for edges.
static int ENTITY_REQUEST
          A request for entities, a/k/a search.
static byte FLAG_NO_CACHE
          The flag used to indicate that this response is valid for this request only.
static String FLAGS
          Key for the flags attribute
static byte FLAGS_DEFAULT
          A constant for default flags.
static int ID_REQUEST
          Get an entity id.
static int LIST_ENTITIES_REQUEST
          List all entities in the datasource.
static int METADATA_REQUEST
          Get all metadata for this datasource.
static String NODE
          The entity type for nodes.
static int NULL_REQUEST
          A non-request.
static String QUERY_MAX_RESULTS
          Key for the amount of results allowed in a query
static String QUERY_STARTING_RESULT_NUMBER
          Key for the starting result number in a query
static String QUERY_STRING
          Key for the query string, for requests that require one.
static int RELATED_REQUEST
          Find out which entities are related.
static int RESERVED_ID_MAX
          Define your own request types to be greater than this.
static String SINK
          The relation type for an entity related as a sink.
static String SOURCE
          The relation type for an entity related as a source.
static String TOTAL_RESULTS
          Key for the total number of results returned by a query
static int UNLIMITED_RESULTS
           
static int UPDATE_REQUEST
          Update an entity.
 
Method Summary
 void attribute(String name, Object value)
          Send a message attribute.
 void beginEntity()
          Begin an entity.
 void beginEntityMD(String parentType)
          Begin entity metadata.
 void beginId(String entityType)
          Begin an entity ID.
 void beginMessage(int messageType)
          Begin a message.
 void beginRelatedEntity(String propertyName, boolean reciprocal)
          A related entity.
 void beginRelatedList(byte relatedFlag)
          Begin the list of related entities.
 void endEntity()
          End an entity.
 void endEntityMD()
          End entity metadata.
 void endId()
          End an entity ID.
 void endMessage()
          End a message.
 void endRelatedEntity()
          End a related entity.
 void endRelatedList()
          Mark the end of a related list.
 void error(Exception e)
          Tell the entity source about an error.
 void fatalError(Exception e)
          A fatal error occured.
 void idKey(Object key)
          Send an id key.
 void idKeyMD(Class keyClass)
          Describe an entity id's key.
 void property(String name, Object value)
          Send an entity's property.
 void propertyMD(String name, Class type)
          Describe an entity's property.
 

Field Detail

NULL_REQUEST

static final int NULL_REQUEST
A non-request.

See Also:
Constant Field Values

ID_REQUEST

static final int ID_REQUEST
Get an entity id. The string format of the ID should be sent in the QUERY_STRING message attribute. Ideally a datasource will parse eg MOVIE:12 correctly.

See Also:
Constant Field Values

ENTITY_REQUEST

static final int ENTITY_REQUEST
A request for entities, a/k/a search. Pass a search string in the QUERY_STRING message attribute.

See Also:
Constant Field Values

RELATED_REQUEST

static final int RELATED_REQUEST
Find out which entities are related. Send an entity ID in the request.

See Also:
Constant Field Values

METADATA_REQUEST

static final int METADATA_REQUEST
Get all metadata for this datasource.

See Also:
Constant Field Values

UPDATE_REQUEST

static final int UPDATE_REQUEST
Update an entity. Pass an entity with new values for properties.

See Also:
Constant Field Values

ADD_REQUEST

static final int ADD_REQUEST
Add a new entity.

See Also:
Constant Field Values

DELETE_REQUEST

static final int DELETE_REQUEST
Delete an entity.

See Also:
Constant Field Values

LIST_ENTITIES_REQUEST

static final int LIST_ENTITIES_REQUEST
List all entities in the datasource.

See Also:
Constant Field Values

RESERVED_ID_MAX

static final int RESERVED_ID_MAX
Define your own request types to be greater than this.

See Also:
Constant Field Values

FLAGS_DEFAULT

static final byte FLAGS_DEFAULT
A constant for default flags.

See Also:
Constant Field Values

FLAG_NO_CACHE

static final byte FLAG_NO_CACHE
The flag used to indicate that this response is valid for this request only. If this bit is set, a subsequent request, even with the same parameters, may return different results. The client will not cache these results.

Caching is the default.

See Also:
Constant Field Values

UNLIMITED_RESULTS

static final int UNLIMITED_RESULTS
See Also:
Constant Field Values

ATTR_CACHE_REVISION

static final String ATTR_CACHE_REVISION
An attribute for version numbers of things in caches

See Also:
Constant Field Values

QUERY_STRING

static final String QUERY_STRING
Key for the query string, for requests that require one.

See Also:
Constant Field Values

QUERY_MAX_RESULTS

static final String QUERY_MAX_RESULTS
Key for the amount of results allowed in a query

See Also:
Constant Field Values

QUERY_STARTING_RESULT_NUMBER

static final String QUERY_STARTING_RESULT_NUMBER
Key for the starting result number in a query

See Also:
Constant Field Values

TOTAL_RESULTS

static final String TOTAL_RESULTS
Key for the total number of results returned by a query

See Also:
Constant Field Values

FLAGS

static final String FLAGS
Key for the flags attribute

See Also:
Constant Field Values

NODE

static final String NODE
The entity type for nodes. Send this as the prototype in metadata.

See Also:
Constant Field Values

EDGE

static final String EDGE
The entity type for edges. Send this as the prototype in metadata.

See Also:
Constant Field Values

SOURCE

static final String SOURCE
The relation type for an entity related as a source.

See Also:
Constant Field Values

SINK

static final String SINK
The relation type for an entity related as a sink.

See Also:
Constant Field Values
Method Detail

beginMessage

void beginMessage(int messageType)
Begin a message.

Parameters:
messageType - one of the request types below, eg RELATED_REQUEST

attribute

void attribute(String name,
               Object value)
Send a message attribute. See the grammar above; this is sent only at the top level of a message, before entities (if any) are sent.

Parameters:
name - The attribute's name
value - The attribute's value

beginEntity

void beginEntity()
Begin an entity.


endEntity

void endEntity()
End an entity.


beginEntityMD

void beginEntityMD(String parentType)
Begin entity metadata.

Parameters:
parentType - The parent type of this entity, eg NODE or EDGE.

endEntityMD

void endEntityMD()
End entity metadata.


property

void property(String name,
              Object value)
Send an entity's property. Primary data-transmission point.


propertyMD

void propertyMD(String name,
                Class type)
Describe an entity's property.


beginId

void beginId(String entityType)
Begin an entity ID.

Parameters:
entityType - The type of entity being sent.

endId

void endId()
End an entity ID.


idKey

void idKey(Object key)
Send an id key.

Parameters:
key - A key in an entity ID.

idKeyMD

void idKeyMD(Class keyClass)
Describe an entity id's key.

Parameters:
keyClass - Describe an entity ID's key.

beginRelatedList

void beginRelatedList(byte relatedFlag)
Begin the list of related entities.

Parameters:
relatedFlag - one of: FLAGS_DEFAULT, FLAG_NO_CACHE

endRelatedList

void endRelatedList()
Mark the end of a related list.


beginRelatedEntity

void beginRelatedEntity(String propertyName,
                        boolean reciprocal)
A related entity. Generally only EDGEs have related entities, and they have two of them (SOURCE and SINK).

Parameters:
propertyName - either SOURCE or SINK.
reciprocal - should this connection go both ways? SOURCE should always be reciprocal, and SINK should be reciprocal for a bidirectional edge.

endRelatedEntity

void endRelatedEntity()
End a related entity.


endMessage

void endMessage()
End a message.


error

void error(Exception e)
Tell the entity source about an error. The message must still be well- formed; this is not an abort.

Parameters:
e - The cause.

fatalError

void fatalError(Exception e)
A fatal error occured. This is an abort, so don't expect the message to be properly finished.

Parameters:
e - The cause.


Copyright © 2013 Thinkmap, Inc. All Rights Reserved.