i3.dragos.gm.core
Interface GraphPool

All Superinterfaces:

MetaAttributable

All Known Implementing Classes:

FilteringGraphPool

public interface GraphPool
extends MetaAttributable

A GraphPool manages graphs which are stored in the same data source.

A graph pool always is in one of two states: opened or closed. Most methods will only work if the pool is opened!

All implementations of GraphPool must provide a public constructor accepting a DataSourceURL as the only parameter. The GraphPoolFactory will not be able to instantiate them otherwise.

Author:

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

See Also:

Core Graph Model, Implementation Issues

Method Summary

void	clear(boolean alsoClearSchema) Removes every graph entity from this graph pool, and possibly every class declaration from the schema.
void	close() Closes the graph pool and frees all temporary resources used by it.
Graph	createTopLevelGraph(java.lang.String name, GraphClass type) Creates a new (top-level) graph with the given name.
boolean	existsTopLevelGraph(java.lang.String name) Returns true if a graph identified by the name is stored in the pool and false otherwise.
java.util.Collection<? extends GraphEntity>	getAllInstances(GraphEntityClass id) Returns all instances of a GraphEntityClass contained in the pool.
java.util.Collection<? extends Graph>	getAllTopLevelGraphs() Returns all top-level graphs (those which have no parent graph) stored in this graph pool.
DataSourceURL	getDataSourceURL() Returns the URL to the data source of this graph pool.
boolean	getForceExistenceCheckOnRead() Tells wether the existence of any entity or entity class is checked before performing a reading operation.
GraphEntity	getGraphEntityByInternalIdentifier(java.io.Serializable identifier) Retrieves a GraphEntity by its internal identifier.
DefaultGraphPoolChecker	getGraphPoolChecker() Returns the GraphPoolChecker used by the GraphPool, which will always be an instance of DefaultGraphPoolChecker.
Schema	getSchema() Returns the schema used for all elements in this graph pool.
Graph	getTopLevelGraphByName(java.lang.String name) Returns the top-level graph identified by the specified name.
GraphPool	getWrappedGraphPool() Returns the wrapped graph pool, null if none.
Wrapper	getWrapper() Returns the Wrapper currently used by the GraphPool.
void	init() Initializes a graph pool.
void	open() Prepares the graph pool for normal operation.
void	removeAllAttributeInstances(Attribute attribute) Removes every instance of an attribute from the pool.
void	removeAllInstances(GraphEntityClass id) Removes every instance of a GraphEntityClass from the pool.
void	removeTopLevelGraph(Graph graph) Deletes a top-level graph.
void	reorganizePool() Reorganizes the entire graph pool.
void	setForceExistenceCheckOnRead(boolean b) Sets wether the existence of any entity or entity class is checked before performing a reading operation.
void	setWrapper(Wrapper w) Sets the Wrapper to be used by the GraphPool.

Methods inherited from interface i3.dragos.gm.core.schema.MetaAttributable

getAllMetaAttributes, getMetaAttribute, isMetaAttributeKeyReserved, isMetaAttributeSet, setMetaAttribute, unsetMetaAttribute

Method Detail

getDataSourceURL

DataSourceURL getDataSourceURL()

Returns the URL to the data source of this graph pool. The returned value can not be null.

This method must work even when the GraphPool is closed.

Returns:

the URL to the data source of this graph pool.

getSchema

Schema getSchema()
                 throws DragosException

Returns the schema used for all elements in this graph pool.

This method must work even when the GraphPool is closed.

Returns:

schema used for all elements in this graph pool.

Throws:

DragosException - if something went wrong.

createTopLevelGraph

Graph createTopLevelGraph(java.lang.String name,
                          GraphClass type)
                          throws EntityNotFoundException,
                                 DragosException,
                                 java.lang.IllegalArgumentException,
                                 EntityAlreadyExistsException,
                                 GraphEntityInstantiationException

Creates a new (top-level) graph with the given name.

Parameters:

name - The name of the graph.

type - The graphs type.

Returns:

A new graph of the specified name.

Throws:

EntityNotFoundException - if the type could not be found.

java.lang.IllegalArgumentException - if name or type are null.

EntityAlreadyExistsException - if a graph with this name already exists.

GraphEntityInstantiationException - if type is declared as an abstract class.

DragosException - if something went wrong.

existsTopLevelGraph

boolean existsTopLevelGraph(java.lang.String name)
                            throws DragosException

Returns true if a graph identified by the name is stored in the pool and false otherwise.

Parameters:

name - The name of the graph.

Returns:

true if a graph identified by the name is stored in the pool and false otherwise.

Throws:

DragosException - if something went wrong.

removeTopLevelGraph

void removeTopLevelGraph(Graph graph)
                         throws EntityNotFoundException,
                                DragosException

Deletes a top-level graph.

See Graph.removeGraphEntity(GraphEntity) for a detailed description on the deletion process.

Any non-top-level graphs should be deleted by calling Graph.removeGraphEntity(GraphEntity) on their parent graph instead.

Parameters:

graph - The graph.

Throws:

EntityNotFoundException - if the graph is not a top-level graph in this GraphPool.

DragosException - if something went wrong.

getAllTopLevelGraphs

java.util.Collection<? extends Graph> getAllTopLevelGraphs()
                                                           throws DragosException

Returns all top-level graphs (those which have no parent graph) stored in this graph pool. The elements in the collection are of type Graph.

Returns:

A Collection of Graphs (may be empty, but never null).

Throws:

DragosException - in case of internal errors.

getTopLevelGraphByName

Graph getTopLevelGraphByName(java.lang.String name)
                             throws EntityNotFoundException,
                                    DragosException

Returns the top-level graph identified by the specified name.

Parameters:

name - The name of the graph.

Returns:

The graph associated with the name.

Throws:

EntityNotFoundException - if the graph does not exist.

DragosException - if something else went wrong.

getGraphEntityByInternalIdentifier

GraphEntity getGraphEntityByInternalIdentifier(java.io.Serializable identifier)
                                               throws EntityNotFoundException,
                                                      DragosException

Retrieves a GraphEntity by its internal identifier.

Parameters:

identifier - The internal identifier.

Returns:

The requested GraphEntity (subclass).

Throws:

EntityNotFoundException - if the graph entity does not exist.

DragosException - if something else went wrong.

clear

void clear(boolean alsoClearSchema)
           throws DragosException

Removes every graph entity from this graph pool, and possibly every class declaration from the schema. This method does not require implementations to remove all elements one-by-one from the underlying datasource. Only the firing of an according GraphPoolEvent is required.

Parameters:

alsoClearSchema - Whether Schema.clear() should be called after successful removal of all entities in the pool.

Throws:

DragosException - if something went wrong.

getAllInstances

java.util.Collection<? extends GraphEntity> getAllInstances(GraphEntityClass id)
                                                            throws EntityNotFoundException,
                                                                   DragosException

Returns all instances of a GraphEntityClass contained in the pool.

Parameters:

id - The class whose instances are to be returned.

Returns:

All instances of a GraphEntityClass contained in the pool.

Throws:

EntityNotFoundException - if the class was not found in the schema.

DragosException - if something went wrong.

removeAllInstances

void removeAllInstances(GraphEntityClass id)
                        throws EntityNotFoundException,
                               DragosException

Removes every instance of a GraphEntityClass from the pool.

Deletion must follow the general procedure for deletion of graph entities, described at Graph.removeGraphEntity(GraphEntity).

The easiest way to ensure this is to proceed as follows for every graph entity in this pool:

• For top-level graphs call removeTopLevelGraph(Graph).
• For all other graph entities call Graph.removeGraphEntity(GraphEntity) on their parent graph.

Implementation notice: Some instances might already be deleted due to cascading removal of entities processed before, so take care when iterating through the instances.

Parameters:

id - The class whose instances are to be deleted.

Throws:

EntityNotFoundException - if the class was not found in the schema.

DragosException - if something went wrong.

removeAllAttributeInstances

void removeAllAttributeInstances(Attribute attribute)
                                 throws EntityNotFoundException,
                                        DragosException

Removes every instance of an attribute from the pool. This includes occurences marked as invalid (if such data is not discarded immediately upon invalidation) to avoid zombies.

Parameters:

attribute - The attribute whose instances are to be deleted.

Throws:

EntityNotFoundException - if the attribute definition was not found in the schema.

DragosException - if something went wrong.

reorganizePool

void reorganizePool()
                    throws EntityInUseException,
                           DragosException

Reorganizes the entire graph pool. This includes

• Removal of all kinds of unused informations
• Compaction of informations
• Release of all existing locks (due to crashes)
• ...

Any information that is used by applications to access any kind of information externally visible (like internal identifiers) will not be modified.

Caution: This method should only be used by privileged application modules because exclusive access to the graph pool is required in general.

Throws:

EntityInUseException - if the graph use by some other component.

DragosException - if something went wrong.

close

void close()
           throws GraphPoolException

Closes the graph pool and frees all temporary resources used by it. The data stored in the graph pool is not deleted! If the pool is already closed, a call to this method will have no effect.

This method must work even when the GraphPool is closed.

Throws:

GraphPoolException - if something went wrong.

See Also:

open()

open

void open()
          throws GraphPoolException

Prepares the graph pool for normal operation. If the pool is already opened, a call to this method will have no effect.

This method must work even when the GraphPool is closed.

Throws:

GraphPoolException - if something went wrong.

See Also:

close()

init

void init()
          throws GraphPoolException

Initializes a graph pool. Implementations have to comply to the this contract:

• If this pool wraps another pool, the wrapped pool's init method must be called first
• subsequent calls to this method on already initialized graph pool may have no effect

The application has to ensure that

• this method is only called on opened graph pools
• a transaction is active on the DataSource and accessible via the TransactionManagerFactory
• the method is called at least once before the first access to the graph pool after open()

Throws:

GraphPoolException - if something went wrong.

setForceExistenceCheckOnRead

void setForceExistenceCheckOnRead(boolean b)

Sets wether the existence of any entity or entity class is checked before performing a reading operation. See the "Consistency" section in the documentation for details.

Parameters:

b - The new value of the flag.

getForceExistenceCheckOnRead

boolean getForceExistenceCheckOnRead()

Tells wether the existence of any entity or entity class is checked before performing a reading operation. See the "Consistency" section in the documentation for details.

Returns:

The value of the flag.

getWrapper

Wrapper getWrapper()

Returns the Wrapper currently used by the GraphPool. Since any GraphPool is initialized with a NullWrapper upon creation, and setWrapper(Wrapper) does not allow a null argument, the returned value is guaranteed not to be null.

The Wrapper itself must not be modified after it has been set, the wrapping mechanism should be immutable! Rationale: We want to allow the caching of wrapped entities, and changes directly to the Wrapper will not be noticed by the GraphPool, meaning entities wrapped according to the old rules may remain in the caches and still be returned! To change the Wrapper, e.g. add a new layer to a MultiWrapper, create a completely new Wrapper and set it using this method. The GraphPool will take this as a sign to discard not only the old Wrapper, but also any caches associated with it!

This method must work even when the GraphPool is closed.

Returns:

the Wrapper currently used by the GraphPool.

See Also:

Wrapper

setWrapper

void setWrapper(Wrapper w)
                throws DragosException

Sets the Wrapper to be used by the GraphPool. If you do not need any additional functionality, use the NullWrapper (which is the default Wrapper set upon GraphPool creation)

This method must work even when the GraphPool is closed.

Parameters:

w - the Wrapper to be used by the GraphPool (must not be null).

Throws:

DragosException - if something went wrong.

See Also:

Wrapper

getWrappedGraphPool

GraphPool getWrappedGraphPool()

Returns the wrapped graph pool, null if none.

If there is more than one instance of any sub-interface or implementing class in the wrapper chain, partial unwrapping (needed mostly to access newly defined methods) may not work as expected. It is up to the application to ensure that no wrapper is included more than once.

This method must work even when the GraphPool is closed.

Returns:

the wrapped GraphPool, null if none.

See Also:

GraphPoolFactory.unwrapGraphPoolTill(GraphPool, ExtensionDescriptor)

getGraphPoolChecker

DefaultGraphPoolChecker getGraphPoolChecker()

Returns the GraphPoolChecker used by the GraphPool, which will always be an instance of DefaultGraphPoolChecker. You can however use DefaultGraphPoolChecker.addCustomGraphPoolChecker(GraphPoolChecker) to add additional, custom checks that will be performed after the default tests have passed. The default checker can not be deactivated without modifying the source code. This makes sense because the default checker simply enforces assumptions also made by implementations, so loosening its restrictions would result in unpredictable behaviour and errors. If you change the whole graph model implementation to deal with different assumptions anyway, deactivating the default checker should be easy.

This method must work even when the GraphPool is closed.

Returns:

the DefaultGraphPoolChecker used by the GraphPool (which is never null).

See Also:

GraphPoolChecker, DefaultGraphPoolChecker