org.activemath.abstractcontent
Interface MBaseRef

All Known Subinterfaces:

AuthorExtendedMBaseRef

All Known Implementing Classes:

CachedMBaseRef, CascadingMBaseRef, MBaseCacheRef, MultiMBase, OJXmlRpcMBaseRef, OmdocJdomMBaseRef, OmdocLuceneMBaseRef, SluMBaseRef, SluMBaseRefForTesting, TheMBaseXmlRpcClient

public interface MBaseRef

A generic interface to mark a reference to an existing database of OMDoc documents.

Implementations of such an interface are expected to be obtained by a configuration or context, for example thanks to Subconfiguration.getService(String).

Be very careful with result JDOM elements: the elements are not supposed to be free of parents or any other structure. It is therefore advised to test on a possible parent before adding them as child of another element, or catch a possible IllegalAddException. Note: currently, getDefinitions and getForWhat return MBaseID[] instead of Iterator, which most of the other methods do. This is due to java lacking polymorphism over return types; therefore, having these methods return iterator won't allow XmlRPCMBase to implement both old and new style interfaces.

Nested Class Summary

static class	MBaseRef.Dependency A useful class to describe a relation between two items as returned by getDependencies(org.activemath.abstractcontent.MBaseID) and getRelated(org.activemath.abstractcontent.MBaseID, java.util.Collection).
static interface	MBaseRef.Relation

Method Summary

void	assertItsUp() Asserts that the database connection is up and running.
String	getAttribute(MBaseID id, String attributeName) Returns the attribute value of the attribute of given name of the element with given ID.
MBaseID	getCanonicalID(MBaseID id) Returns a fully-qualified unique ID that enables collections of IDs to behave properly.
OJElement	getChildren(MBaseID id, String xPathReducedExpression) Returns the content of the named descendant of the element of given ID.
Collection	getCollectionsProvided() returns a Collection (object) with the collections (content blocks) provided by this MBaseRef
Map	getCommonName(MBaseID id) Returns the names of this element which is fetched either from the <metadata><dc:Title> descendant or from the <commonname> elements.
OJElement	getCompleteDCMetadata(MBaseID id) Returns a metadata element with only Dublin-Core children including inherited ones from their parents.
Iterator	getDefinitions(MBaseID id, Collection collections) For a symbol, this method returns the IDs of all definitions.
Iterator	getDependencies(MBaseID mBaseID) Gets an Iterator of MBaseRef.Dependency relations with all relations that stem from this element.
OJElement	getFormalContent(MBaseID id) From any ID this method returns the content of the FMP element.
MBaseID[]	getForWhat(MBaseID id) Returns the ID contained in the attribute for
Iterator	getIncomingRelations(MBaseID id, Collection collections) Returns an iterator of MBaseRef.Relations objects describing the relations that point to this item.
Iterator	getItemsModifiedSince(Date date)
Date	getLastModified(Collection ids) Returns the latest modification dates of the elements whose IDs are given.
OJElement	getMetadata(MBaseID id) Returns the contents of the <metdata> child of this element.
Iterator	getOutgoingRelations(MBaseID id) Returns an iterator of MBaseRef.Relations objects describing the relations that point from this item.
Iterator	getProofs(MBaseID assertionID, Collection collections) For an assertion, this method returns the IDs of all of its proofs.
Iterator	getRelated(MBaseID mBaseID, Collection collections) Same as getDependencies(org.activemath.abstractcontent.MBaseID) but returns the converse: all relations whose MBaseRef.Dependency.idOn is the element of given ID.
OJDocument	getStructuredListOfConcepts(Collection collections) This expensive operation walks the complete XML structure of one single collection stored in the server and creates a theory element for each theory then a concept element for each of the concepts (symbol, definition, assertion, proof, methods).
Map	getTagFreeCommonName(MBaseID id) Returns the titles without any tags, just extracting the text or partially rendering it.
List	getTextualContent(MBaseID id) From any ID this method returns the row of CMP elements' contents.
MBaseID	getTheory(MBaseID id) Returns the ID of the closest parent (including the element itself) that either has a theory attribute or is a theory element or null if there is no such parent.
String	getTypeString(MBaseID id) Returns the name of the element whose ID is given.
Iterator	listItems(Collection collections, String type) Lists all the items being children of the element of the indicated ID.
Iterator	listItems(MBaseID id) Lists all the items being children of the element of the indicated ID.
Iterator	listTheories(Collection collections) Lists all the IDs of the theory elements contained in the indicated collections .
Iterator	searchText(String textToSearch, Collection collections) Searches the union of all text elements, but not the attributes, for the given substring in a case-sensistive manner.

Method Detail

getDependencies

Iterator getDependencies(MBaseID mBaseID)
                         throws MBaseException

Gets an Iterator of MBaseRef.Dependency relations with all relations that stem from this element. Relations are considered the same as dependencies in this class. They are of many types as described in the MBaseRef.Dependency class. Use getDependencies(org.activemath.abstractcontent.MBaseID) to read the list of relations that stem from another element but target this element.

Note that the server implementation is not required to return all these types only the content of the <depends-on> elements are required to be returned.

Parameters:

mBaseID - which's dependencies are to be returned

Returns:

Iterator of MBaseIDs that are dependent

Throws:

MBaseException - if something's wrong, i.e. if a collection was queried that is not provided

getRelated

Iterator getRelated(MBaseID mBaseID,
                    Collection collections)
                    throws MBaseException

Same as getDependencies(org.activemath.abstractcontent.MBaseID) but returns the converse: all relations whose MBaseRef.Dependency.idOn is the element of given ID.

Parameters:

mBaseID - which's relations are to be returned

collections - java.util.Collection of (content) collections as Strings to search in

Returns:

Iterator of MBaseIDs that are dependent

Throws:

MBaseException - if something's wrong.

getChildren

OJElement getChildren(MBaseID id,
                      String xPathReducedExpression)
                      throws MBaseException

Returns the content of the named descendant of the element of given ID. The descendant are found using the xPathReducedExpression parameter which aims at imitating an XPath expression except it only accepts the ., / and named elements.

This walks the tree of descendants, taking children everytime a /elementName is found in the xPathReducedExpression and returns the content of the end child.

Such a method might be a warmer future for all requests, including getDependencies, getMetaData and getCommonName.

Parameters:

id - the MBaseID to get the children of

xPathReducedExpression - as described above

Returns:

the OJElement thus crafted

Throws:

MBaseException - if something fails

getAttribute

String getAttribute(MBaseID id,
                    String attributeName)
                    throws MBaseException

Returns the attribute value of the attribute of given name of the element with given ID. throws MBaseException if something fails

Parameters:

id - the id of the XML element that is to be looked for

attributeName - the name of the attribute to be looked for in this element

Returns:

the attribute value

Throws:

MBaseException - if anything goes wrong

getDefinitions

Iterator getDefinitions(MBaseID id,
                        Collection collections)
                        throws MBaseException

For a symbol, this method returns the IDs of all definitions.

Parameters:

id - id the id of the symbol whose definitions are looked at

collections - collections the name of the collections to be searched

Returns:

null for non-symbol elements or if no definition is found.

Throws:

MBaseException - if something's wrong.

getProofs

Iterator getProofs(MBaseID assertionID,
                   Collection collections)
                   throws MBaseException

For an assertion, this method returns the IDs of all of its proofs.

Parameters:

assertionID - MBaseID denoting the assertion whose proofs are to be searched

collections - Collection of (content) collections to search in

Returns:

an Iterator with the proofs, that is empty for non-assertion elements or if no proof is found.

Throws:

MBaseException - if something's wrong.

getTextualContent

List getTextualContent(MBaseID id)
                       throws MBaseException

From any ID this method returns the row of CMP elements' contents. The server is supposed to "resolve" the occurrences of <OMS> who are "referenced" by means of the xref attribute.

Parameters:

id - The ID of the item whose CMPs are to be returned

Returns:

A list of OJElements being the CMP nodes

Throws:

MBaseException - if something fails

getFormalContent

OJElement getFormalContent(MBaseID id)
                           throws MBaseException

From any ID this method returns the content of the FMP element. The server is supposed to "resolve" the occurrences of <OMS> who are "referenced" by means of the xref attribute.

Parameters:

id - The ID whose FMP child is to be fetched

Returns:

a the OJElement representing the <FMP> or null if there is no <FMP> content behind the ID

Throws:

MBaseException - if something fails

getMetadata

OJElement getMetadata(MBaseID id)
                      throws MBaseException

Returns the contents of the <metdata> child of this element. This does not apply the inheritance principles of Dublin-Core metadata (as described in OMDoc 1.1 specifications), please use getCompleteDCMetadata(org.activemath.abstractcontent.MBaseID) for this task.

Parameters:

id - The ID of the item whose metadata element is to be fetched.

Returns:

The metadata OJElement

Throws:

MBaseException - if something fails

getCompleteDCMetadata

OJElement getCompleteDCMetadata(MBaseID id)
                                throws MBaseException

Returns a metadata element with only Dublin-Core children including inherited ones from their parents. The inheritance is described in OMDoc 1.1 specifications (i.e. added values with children taking precedence when a triple (language, element-name, role) also exists.

This allows most of the copyright informations to be stored in the metadata element of the OMDoc while additions can override or enrich these values.

Parameters:

id - the ID of the item whose metadata is to be fetched

Returns:

the completed OJElement metadata node

Throws:

MBaseException - If anything happens

getTheory

MBaseID getTheory(MBaseID id)
                  throws MBaseException

Returns the ID of the closest parent (including the element itself) that either has a theory attribute or is a theory element or null if there is no such parent.

Parameters:

id - The item whose theory is to be found

Returns:

The MBaseID of the related theory element

Throws:

MBaseException - if something's wrong.

getCommonName

Map getCommonName(MBaseID id)
                  throws MBaseException

Returns the names of this element which is fetched either from the <metadata><dc:Title> descendant or from the <commonname> elements.

The table returned has, as keys, the language and as values the text of this common-name.

Parameters:

id - The ID of the item whose titles are to be looked at.

Returns:

A Map of titles (keys String language}, values the String titles

Throws:

MBaseException - if something's wrong.

getTypeString

String getTypeString(MBaseID id)
                     throws MBaseException

Returns the name of the element whose ID is given.

Parameters:

id - The ID of the element

Returns:

The (XML) element-name of this node

Throws:

MBaseException - if something's wrong.

getForWhat

MBaseID[] getForWhat(MBaseID id)
                     throws MBaseException

Returns the ID contained in the attribute for

Parameters:

id - The ID of the item whose for attribute is to be looked at.

Returns:

The list of pointers interpreted from the pointer values in the for attribute of the element

Throws:

MBaseException - if something's wrong.

searchText

Iterator searchText(String textToSearch,
                    Collection collections)
                    throws MBaseException

Searches the union of all text elements, but not the attributes, for the given substring in a case-sensistive manner. This operation is expected to be rather expensive.

Parameters:

textToSearch - String containing the text to be searched

collections - Collection of collections (as Strings) to search in

Returns:

an Iterator of MBaseIDs that contain the string

Throws:

MBaseException - if something's wrong.

listItems

Iterator listItems(MBaseID id)
                   throws MBaseException

Lists all the items being children of the element of the indicated ID. Implementations are required to support this operation on omgroup and theory elements only.

Parameters:

id - the ID of the omgroup, theory or other element

Returns:

An iterator of MBaseID objects

Throws:

MBaseException - If anything goes wrong

listItems

Iterator listItems(Collection collections,
                   String type)
                   throws MBaseException

Lists all the items being children of the element of the indicated ID. Implementations are required to support this operation on omgroup and theory elements only.

Parameters:

collections - the possible collections where to search for the items of this type

type - the element name wished to be returne

Returns:

An iterator of MBaseID objects to the given elements

Throws:

MBaseException - If anything goes wrong

listTheories

Iterator listTheories(Collection collections)
                      throws MBaseException

Lists all the IDs of the theory elements contained in the indicated collections .

Parameters:

collections - the set of collection-names to be walked through for theories.

Returns:

an iterator over the list of IDs that are children

Throws:

MBaseException - If anything goes wrong

getStructuredListOfConcepts

OJDocument getStructuredListOfConcepts(Collection collections)
                                       throws MBaseException

This expensive operation walks the complete XML structure of one single collection stored in the server and creates a theory element for each theory then a concept element for each of the concepts (symbol, definition, assertion, proof, methods).

Parameters:

collections - strings with the name of the collection to search in

Returns:

an XML document structured by theory/element, or null, if there are no contents found

Throws:

MBaseException - if something fails

assertItsUp

void assertItsUp()
                 throws MBaseException

Asserts that the database connection is up and running. This may include a self test, so use only in code for test purposes (such as in an appropriate checker) or in non-looped code (once at startup or something).

Throws:

MBaseException - if something's wrong.

getCollectionsProvided

Collection getCollectionsProvided()
                                  throws MBaseException

returns a Collection (object) with the collections (content blocks) provided by this MBaseRef

Returns:

Collection of Strings with the names of the provided collections

Throws:

MBaseException - If anything goes wrong (normally nothing is expected to go wrong here)

getCanonicalID

MBaseID getCanonicalID(MBaseID id)
                       throws MBaseException

Returns a fully-qualified unique ID that enables collections of IDs to behave properly. MBase engines may allow heuristics to interpret IDs, among others, to identify an item with an ID not containing a theory although the item is in a theory.

MBase engines should be consistent and never return more than one ID for a given item.

Parameters:

id - the id that may be missing a theory or collection.

Returns:

a fully-qualified absolute ID pointing to the same element, or null if no such element was found.

Throws:

MBaseException - If anything goes wrong

getLastModified

Date getLastModified(Collection ids)
                     throws MBaseException

Returns the latest modification dates of the elements whose IDs are given.

Parameters:

ids - a list of MBaseIDs of items, theories, or Strings of collection name

Returns:

the latest modification date or, if unknown, the current date.

Throws:

MBaseException

getItemsModifiedSince

Iterator getItemsModifiedSince(Date date)
                               throws MBaseException

Throws:

MBaseException

getTagFreeCommonName

Map getTagFreeCommonName(MBaseID id)
                         throws MBaseException

Returns the titles without any tags, just extracting the text or partially rendering it. Useful for string-only processors.

Parameters:

id - the item id.

Returns:

the map, associating a language string to a title-string.

Throws:

MBaseException

getIncomingRelations

Iterator getIncomingRelations(MBaseID id,
                              Collection collections)
                              throws MBaseException

Returns an iterator of MBaseRef.Relations objects describing the relations that point to this item. If the item is a theory, the relations are the imports statements.

Parameters:

id - the id from which to see the relations

collections - from where should these relations be incoming

Returns:

an iterator of MBaseRef.Relations objects

Throws:

MBaseException - if anything

getOutgoingRelations

Iterator getOutgoingRelations(MBaseID id)
                              throws MBaseException

Returns an iterator of MBaseRef.Relations objects describing the relations that point from this item. If the item is a theory, the relations are the imports statements.

Parameters:

id - the id from which to see the relations

Returns:

an iterator of MBaseRef.Relations objects

Throws:

MBaseException - if anything