Package org.ogf.saga.isn

Provides interfaces to retrieve data from an information model.

See: Description

Interface Summary

Interface	Description
EntityData	Provides read access to the data of an entity.
EntityDataSet	Provides the means to navigate around the information model for a selected entity and gives access to the EntityData objects.

Class Summary

Class	Description
ISNFactory	Factory for objects of the information system navigator package.

Package org.ogf.saga.isn Description

Provides interfaces to retrieve data from an information model.

A possible starting point for navigation would be a service, as selected with the org.ogf.saga.sd.Discoverer API. Alternatively it is possible to start with a selected entity type rather than a service. An optional filter can be used to restrict the results returned. It is expected that this Information System Navigator API will make use of various information systems. The quality of the information returned will depend upon the quality of the data in the back-end system or systems.

Information Model

This API can be used to navigate any information system that can be represented as an entity relationship model.

Classes

This API has a ISNFactory class for the creation of EntityDataSet objects.

The EntityDataSet class contains a set of EntityData objects.The EntityDataSet interface has three methods: getData, listRelatedEntityNames and getRelatedEntities. The getData method returns a list of objects of the EntityData class, with each EntityData object representing an instance of an entity as described in the GLUE entity relationship model. The listRelatedEntityNames method returns a list of names of entities for use with the getRelatedEntities method, with the names represent the entities, in the GLUE entity relationship model, that can be navigated to from the current entity. The getRelatedEntities method returns an object of the EntityDataSet class, filtered according to a specified filter (see below).

The EntityData class implements the org.ogf.saga.attributes.Attributes interface giving ReadOnly access to all the key names and values in the EntityData object.

Filters

Both the constructor for the EntityDataSet and the listRelatedEntityNames method take a filter string as an argument. This filter string is used to restrict the set of entities returned. The filter MUST only include attributes from the named entity for the constructor or from the related entity for the listRelatedEntityNames method. The filter strings uses SQL92 syntax as if it were part of a WHERE clause acting to select from a single table. SQL92 has been chosen because it is widely known and has the desired expressive power. Multi-valued attributes are treated as a set of values.

Only the following operators are permitted in expressions not involving multi-valued attributes: IN, LIKE, AND, OR, NOT, =, >=, >, <=, <, <> in addition to column names, parentheses, column values as single quoted strings, numeric values and the comma. For a multi-valued attribute, the name of the attribute MUST have the keyword ALL or ANY immediately before it, unless comparison with a set literal is intended. For each part of the expression, the attribute name MUST precede the literal value. An implementation SHOULD try to give an informative error message if the filter string does not conform.

The LIKE operator matches string patterns:

'%xyz' matches all entries with trailing xyz

'xyz%' matches all entries with leading xyz

'%xyz%' matches all entries with xyz being a substring

The ESCAPE keyword can be used with LIKE in the normal way.

Column names are not case sensitive but values are.

No use-case has been identified for the operators >=, >, <=, > to be applied to strings. An Implementation wishing to support these comparison operators on strings MUST select a collation sequence. Alternatively, an implementation CAN treat all string comparisons as true, or reject them as invalid SQL.

Details

This API will typically use some underlying information system. It may try to use an underlying information system but not be able to access it. The precise behaviour is implementation dependent - for example if it uses adapters it may try a different one. If no result can be returned because of information system or other internal problems, it SHOULD throw the org.ogf.saga.error.NoSuccessException exception.

Since:

not released