i3.dragos.gm.core
Class GraphPoolFactory

java.lang.Object
  i3.dragos.gm.core.GraphPoolFactory

public final class GraphPoolFactory
extends java.lang.Object

The GraphPoolFactory is responsible for creating and opening graph pools. A graph pool is uniquely identified by a datasource URL which are defined in the DataSourceURL class.

There are two kinds of DataSourceURLs:

1. "Physical" DataSourceURLs, which include information about the implementation to use and implementation-specific settings. They are only used once during initialization (see create(DataSourceURL, List, String). After that, the pool is identified by its name or logical DataSourceURL.
2. "Logical" DataSourceURLs, which are constructed from the server's name (see Kernel.getName()) and the pool's name. In the context of a single server, each pool's name is unique and thus sufficent to identify that pool, but in a networked / distributed environment the full DataSourceURL should be used (which of course requires that all servers will have different names).

This factory supports the extension of the core graph model through a standard mechanism centered around extension descriptors.

For a number of reasons ranging from performance to application robustness, all created GraphPools (including the extensions they have been initialized with) are cached. This means that if you want to add, remove or change an extension, you have to restart the kernel. A method to forcibly remove GraphPools from the cache has not been included because ensuring that there is no reference left to a previous GraphPool incarnation is even more work than restarting the kernel.

Author:

Boris Boehlen <boehlen@cs.rwth-aachen.de>, Thorsten Hermes <thermes@i3.informatik.rwth-aachen.de>

See Also:

DataSourceURL

Method Summary

static GraphPool	create(DataSourceURL physicalDataSourceURL, java.util.List<ExtensionDescriptor> extList, java.lang.String name) Returns the graph pool for the given database URL, extended and outfitted with the necessary Wrappers, GraphPoolCheckers and SchemaCheckers as specified by the extension descriptor list.
static GraphPool	get(DataSourceURL dataSourceURL) Returns the graph pool for the given (logical) DataSourceURL.
static GraphPool	getByName(java.lang.String name) Returns the graph pool with the given name.
static GraphPool	getUnwrapped(DataSourceURL dataSourceURL) Returns an unwrapped GraphPool.
static void	registerImplementation(java.lang.String id, java.lang.String impl) Registers a GraphPool implementation.
static GraphPool	unwrapGraphPool(GraphPool graphPool) Completely unwraps a GraphPool.
static GraphPool	unwrapGraphPoolTill(GraphPool graphPool, ExtensionDescriptor extension) Performs unwrapping until an instance of a specified Class is found.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

registerImplementation

public static void registerImplementation(java.lang.String id,
                                          java.lang.String impl)

Registers a GraphPool implementation.

Parameters:

id - The identifier.

impl - The implementation.

get

public static GraphPool get(DataSourceURL dataSourceURL)
                     throws DragosException

Returns the graph pool for the given (logical) DataSourceURL. If no pool for this DataSourceURL has been initialized before, an exception will be thrown.

Parameters:

dataSourceURL - The (logical) DataSourceURL of the pool.

Returns:

The requested GraphPool.

Throws:

DragosException - if no such pool exists.

getByName

public static GraphPool getByName(java.lang.String name)
                           throws DragosException

Returns the graph pool with the given name. If no pool with that name has been initialized before, an exception will be thrown.

Parameters:

name - The name of the pool.

Returns:

The requested GraphPool.

Throws:

DragosException - if no such pool exists.

getUnwrapped

public static GraphPool getUnwrapped(DataSourceURL dataSourceURL)
                              throws GraphPoolException,
                                     DragosException

Returns an unwrapped GraphPool. This is a convenience method for calling GraphPoolFactory.unwrapGraphPool(GraphPoolFactory.get(...))

Parameters:

dataSourceURL - The DataSourceURL of the requested pool.

Returns:

The graph pool.

Throws:

GraphPoolException - (maybe).

DragosException - if something else went wrong.

create

public static GraphPool create(DataSourceURL physicalDataSourceURL,
                               java.util.List<ExtensionDescriptor> extList,
                               java.lang.String name)
                        throws GraphPoolException,
                               DragosException

Returns the graph pool for the given database URL, extended and outfitted with the necessary Wrappers, GraphPoolCheckers and SchemaCheckers as specified by the extension descriptor list.

Subsequent calls with the same DataSourceURL will result in an exception, regardless of the extList value. To retrieve an initialized GraphPool, use get(DataSourceURL) or getByName(String). To add/remove/reorder extension, restart DRAGOS - this also prevents many possible problems due to references to the old GraphPool elsewhere!

This method automatically calls GraphPool.open() before returning the pool.

Order of the extList parameter is important: The innermost layer is at the first position of the list and so on.

As a convenience, the newly created GraphPool is returned. To retrieve it again later, use get(DataSourceURL) with the logical DataSourceURL, or getByName(String) using just the name.

Parameters:

physicalDataSourceURL - The (physical) DataSourceURL of the pool.

extList - A List of ExtensionDescriptors of extensions to activate, may be null or empty.

name - the name to assign to this pool, used to create the (logical) DataSourceURL. Must not be null and must not contain any of the following characters:

 :/&?
 

.

Returns:

The graph pool.

Throws:

GraphPoolException - if the pool can not be opened due to an error on the GraphPool implementation level

DragosException - if the name contained forbidden characters, a pool for that datasourceURL was already initialized, or something else went wrong.

unwrapGraphPoolTill

public static GraphPool unwrapGraphPoolTill(GraphPool graphPool,
                                            ExtensionDescriptor extension)
                                     throws DragosException

Performs unwrapping until an instance of a specified Class is found.

Parameters:

graphPool - The graph pool to unwrap (may not be null).

extension - Defines the graph pool class to look for (may not be null).

Returns:

The first instance of the requested class found.

Throws:

DragosException - if no instance of the requested class was found

unwrapGraphPool

public static GraphPool unwrapGraphPool(GraphPool graphPool)

Completely unwraps a GraphPool.

Parameters:

graphPool - The graph pool to unwrap (may not be null).

Returns:

The unwrapped GraphPool.