org.tm4j.topicmap
Interface TopicMapProvider

All Known Implementing Classes:

TopicMapProviderBase, TopicMapSourceSupport

public interface TopicMapProvider

Interface implemented by an object which wishes to be the source of a TopicMap object.

Field Summary

static boolean	DEFAULT_OPT_MAKE_CONSISTENT
static boolean	DEFAULT_OPT_MERGE_REFS
static boolean	DEFAULT_OPT_NAME_MERGE
static boolean	DEFAULT_OPT_STATIC_MERGE
static java.lang.String	OPT_MAKE_CONSISTENT Provider option to automatically make the topic map XTM consistent after import from a TopicMapSource.
static java.lang.String	OPT_MERGE_REFS Provider option to automatically attempt to retrieve and merge in topic maps referenced from mergeMap elements and by external topic references after parsing from a TopicMapSource.
static java.lang.String	OPT_NAME_MERGE Provider option to create topic maps in which merges are performed based on scoped name.
static java.lang.String	OPT_STATIC_MERGE Provider option to create topic maps in which merges are static.

Method Summary

TopicMap	addTopicMap(java.io.InputStream src, Locator baseLocator, TopicMap existingTopicMap) Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing) instead
TopicMap	addTopicMap(java.io.InputStream src, Locator baseLocator, TopicMap existingTopicMap, Topic[] addedThemes) Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing, Topic[] addedThemes) instead
TopicMap	addTopicMap(java.io.InputStream src, Locator baseLocator, TopicMap existingTopicMap, TopicMapBuilder builder) Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing) instead
TopicMap	addTopicMap(TopicMapSource source) Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource
TopicMap	addTopicMap(TopicMapSource source, Topic[] addedThemes) Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource
TopicMap	addTopicMap(TopicMapSource source, TopicMap existing) Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource
TopicMap	addTopicMap(TopicMapSource source, TopicMap existing, Topic[] addedThemes) Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource
void	close() Closes the provider.
TopicMap	createTopicMap(Locator baseLocator) Creates a new topic map for this provider.
LocatorFactory	getLocatorFactory() Returns the object which may be used to create locator objects in the data store managed by this TopicMapProvider.
ProviderTransaction	getOpenTransaction() Returns the current open transaction
TopicMap	getTopicMap(Locator baseLocator) Returns the topic map provided by this object who's base address is specified by baseLocator.
java.util.Collection	getTopicMapBaseLocators() Returns a collection containing the base Locator of each of the topic maps provided by this TopicMapProvider.
TopicMapBuilder	getTopicMapBuilder(java.lang.String notation) Returns a TopicMapBuilder for building topic maps for the specified notation.
void	init(java.util.Properties props) Sets the runtime properties defined for this TopicMapProvider.
boolean	isTransactional() Indicates whether or not this provider supports transactions.
boolean	isTransactionOpen() Indicates whether or not this provider has a transaction currently open
void	mergeTopicMap(TopicMap baseTopicMap, Locator externalTopicMap, Topic[] addedThemes) Merges the topic map from the resource externalTopicMap into the topic map baseTopicMap.
ProviderTransaction	openTransaction() Opens a new transaction
void	removeTopicMap(TopicMap tm) Removes the specified topic map from this Provider.
boolean	supportsTopicMapNotation(java.lang.String notation) Returns true if notation names a topic map notation that can be parsed by this provider.

Field Detail

OPT_STATIC_MERGE

public static final java.lang.String OPT_STATIC_MERGE

Provider option to create topic maps in which merges are static. Default value = false.

See Also:

Constant Field Values

DEFAULT_OPT_STATIC_MERGE

public static final boolean DEFAULT_OPT_STATIC_MERGE

See Also:

Constant Field Values

OPT_NAME_MERGE

public static final java.lang.String OPT_NAME_MERGE

Provider option to create topic maps in which merges are performed based on scoped name. Default value = true

See Also:

Constant Field Values

DEFAULT_OPT_NAME_MERGE

public static final boolean DEFAULT_OPT_NAME_MERGE

See Also:

Constant Field Values

OPT_MERGE_REFS

public static final java.lang.String OPT_MERGE_REFS

Provider option to automatically attempt to retrieve and merge in topic maps referenced from mergeMap elements and by external topic references after parsing from a TopicMapSource.

See Also:

Constant Field Values

DEFAULT_OPT_MERGE_REFS

public static final boolean DEFAULT_OPT_MERGE_REFS

See Also:

Constant Field Values

OPT_MAKE_CONSISTENT

public static final java.lang.String OPT_MAKE_CONSISTENT

Provider option to automatically make the topic map XTM consistent after import from a TopicMapSource. If set to true, this option automatically implies the option tm4j.merge.referenced.maps.

See Also:

Constant Field Values

DEFAULT_OPT_MAKE_CONSISTENT

public static final boolean DEFAULT_OPT_MAKE_CONSISTENT

See Also:

Constant Field Values

Method Detail

init

public void init(java.util.Properties props)
          throws TopicMapProviderException

Sets the runtime properties defined for this TopicMapProvider. This method will be invoked by the TopicMapProviderFactory when the TopicMapProvider is first created.

Parameters:

props - The parsed set of properties which may be applied to this object.

Throws:

TopicMapProviderException - If the initialisation fails for some reason.

getTopicMap

public TopicMap getTopicMap(Locator baseLocator)
                     throws TopicMapProviderException

Returns the topic map provided by this object who's base address is specified by baseLocator.

Parameters:

baseLocator - The Locator defining the base address of the topic map to be returned.

Returns:

A TopicMap object or null if no topic map with the specified base address is provided by this TopicMapProvider.

Throws:

TopicMapProviderException

createTopicMap

public TopicMap createTopicMap(Locator baseLocator)
                        throws TopicMapProviderException

Creates a new topic map for this provider.

Parameters:

baseLocator - The resource locator for the topic map itself.

Throws:

TopicMapProviderException

getLocatorFactory

public LocatorFactory getLocatorFactory()

Returns the object which may be used to create locator objects in the data store managed by this TopicMapProvider.

addTopicMap

public TopicMap addTopicMap(java.io.InputStream src,
                            Locator baseLocator,
                            TopicMap existingTopicMap)
                     throws TopicMapProviderException

Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing) instead

Imports a topic map in XTM syntax into the data store managed by this TopicMapProvider

Parameters:

src - The InputStream of the XTM data to be read.

baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not have an xml:base attribute on its root element.

existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.

Returns:

The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.

Throws:

TopicMapProviderException

addTopicMap

public TopicMap addTopicMap(java.io.InputStream src,
                            Locator baseLocator,
                            TopicMap existingTopicMap,
                            TopicMapBuilder builder)
                     throws TopicMapProviderException

Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing) instead

Imports a topic map into the data store managed by this TopicMapProvider using the specified builder to parse the input stream.

Parameters:

src - The InputStream of the topic map data to be read.

baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not specify its own base address internally.

existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.

builder - The builder to use in parsing the input stream.

Returns:

The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.

Throws:

TopicMapProviderException - if the parse of the input stream fails for some reason.

addTopicMap

public TopicMap addTopicMap(java.io.InputStream src,
                            Locator baseLocator,
                            TopicMap existingTopicMap,
                            Topic[] addedThemes)
                     throws TopicMapProviderException

Deprecated. use addTopicMap(TopicMapSource source, TopicMap existing, Topic[] addedThemes) instead

Imports a topic map in into the data store using the XTMBuilder class to parse the input stream.

Parameters:

src - The InputStream of the topic map data to be read.

baseLocator - The base address to assign to the generated topic map only if the parsed topic map does not specify its own base address internally.

existingTopicMap - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map parsed from src will be merged with existingTopicMap and no new TopicMap object will be created.

addedThemes - themes to be added to the scope of each ScopedObject created by the import process.

Returns:

The new TopicMap object managed by the TopicMapProvider. If existingTopicMap is not null, then the return value from the function will be the same object as is passed in existingTopicMap. If existingTopicMap is null, then a new TopicMap object will be returned.

Throws:

TopicMapProviderException - if the parse of the input stream fails for some reason.

addTopicMap

public TopicMap addTopicMap(TopicMapSource source,
                            TopicMap existing)
                     throws TopicMapProviderException

Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource

Parameters:

source - a implementation of the TopicMapSource interface representing a source for a TopicMap

existing - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map retrieved from source will be merged with existing TopicMap and no new TopicMap object will be created.

Returns:

The new TopicMap object managed by the TopicMapProvider.

Throws:

TopicMapProviderException - if initialisation or access to the TopicMapSource fails

addTopicMap

public TopicMap addTopicMap(TopicMapSource source,
                            TopicMap existing,
                            Topic[] addedThemes)
                     throws TopicMapProviderException

Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource

Parameters:

source - a implementation of the TopicMapSource interface representing a source for a TopicMap

existing - If this parameter is not null, then the TopicMap object passed in must be a TopicMap which is provided by this TopicMapProvider. The topic map retrieved from source will be merged with existing TopicMap and no new TopicMap object will be created.

addedThemes - themes to be added to the scope of each ScopedObject created by the import process.

Returns:

The new TopicMap object managed by the TopicMapProvider.

Throws:

TopicMapProviderException - if initialisation or access to the TopicMapSource fails

addTopicMap

public TopicMap addTopicMap(TopicMapSource source)
                     throws TopicMapProviderException

Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource

Parameters:

source - a implementation of the TopicMapSource interface representing a source for a TopicMap

Returns:

The new TopicMap object managed by the TopicMapProvider.

Throws:

TopicMapProviderException - if initialisation or access to the TopicMapSource fails

addTopicMap

public TopicMap addTopicMap(TopicMapSource source,
                            Topic[] addedThemes)
                     throws TopicMapProviderException

Imports a topic map into the data store managed by this TopicMapProvider from the specified TopicMapSource

Parameters:

source - a implementation of the TopicMapSource interface representing a source for a TopicMap

addedThemes - themes to be added to the scope of each ScopedObject created by the import process.

Returns:

The new TopicMap object managed by the TopicMapProvider.

Throws:

TopicMapProviderException - if initialisation or access to the TopicMapSource fails

getTopicMapBaseLocators

public java.util.Collection getTopicMapBaseLocators()

Returns a collection containing the base Locator of each of the topic maps provided by this TopicMapProvider.

Returns:

An unmodifiable Collection of Locator objects.

removeTopicMap

public void removeTopicMap(TopicMap tm)
                    throws TopicMapProviderException

Removes the specified topic map from this Provider. If the provider is connected to a persistent store such as a database, this will remove all persistent records of the topic map. If stored in memory, all references to the topic map and its contained objects held by the provider will be freed.

Throws:

TopicMapProviderException

close

public void close()
           throws TopicMapProviderException

Closes the provider. After this call, all references to any topic maps or topic map objects provided by this Provider are invalidated. If the Provider has a connection to a persistant store such as a database, connections may be closed.

Throws:

TopicMapProviderException

mergeTopicMap

public void mergeTopicMap(TopicMap baseTopicMap,
                          Locator externalTopicMap,
                          Topic[] addedThemes)
                   throws TopicMapProviderException

Merges the topic map from the resource externalTopicMap into the topic map baseTopicMap. externalTopicMap will also be removed from this list of external references and mergeMaps for baseTopicMap if it is in one of these lists.

Throws:

TopicMapProviderException - if baseTopicMap is not provided by this provider; or if the parse and merge operation fails for some reason.

isTransactional

public boolean isTransactional()

Indicates whether or not this provider supports transactions.

Returns:

true if the provider supports transactions, false otherwise.

openTransaction

public ProviderTransaction openTransaction()
                                    throws ProviderTransactionException

Opens a new transaction

Returns:

a instance of ProviderTransaction

Throws:

ProviderTransactionException

isTransactionOpen

public boolean isTransactionOpen()

Indicates whether or not this provider has a transaction currently open

Returns:

true if there is an open transaction on the provider, false otherwise.

getOpenTransaction

public ProviderTransaction getOpenTransaction()

Returns the current open transaction

Returns:

the current open transaction or null if there is no transaction open

getTopicMapBuilder

public TopicMapBuilder getTopicMapBuilder(java.lang.String notation)

Returns a TopicMapBuilder for building topic maps for the specified notation.

Parameters:

notation - the name of the notation that the returned TopicMapBuilder must support. Values of 'xtm' and 'ltm' are supported by this distribution of TM4J.

Returns:

a TopicMapBuilder implementation capable of parsing files of the specified notation or null if no such TopicMapBuilder can be found for this TopicMapProvider

supportsTopicMapNotation

public boolean supportsTopicMapNotation(java.lang.String notation)

Returns true if notation names a topic map notation that can be parsed by this provider.

Parameters:

notation -

Returns:

true if notation names a topic map notation that can be parsed by this provider, false otherwise.