com.bigdata.relation
Class AbstractResource<E>

java.lang.Object
  com.bigdata.relation.AbstractResource<E>

Type Parameters:

E -

All Implemented Interfaces:

IMutableResource<E>, ILocatableResource<E>

Direct Known Subclasses:

AbstractRelation, AbstractTripleStore, BigdataFileSystem

public abstract class AbstractResource<E>
extends Object
implements IMutableResource<E>

Base class for locatable resources.

Version:

$Id: AbstractResource.java 6041 2012-02-20 20:46:45Z thompsonbry $

Author:

Bryan Thompson

Nested Class Summary

static interface

AbstractResource.Options Options for locatable resources.

Field Summary

protected static org.apache.log4j.Logger

log

Constructor Summary

protected

AbstractResource(IIndexManager indexManager, String namespace, Long timestamp, Properties properties)

Method Summary

protected IResourceLock	acquireExclusiveLock() Acquires an exclusive lock for the getNamespace().
void	create() Create any logically contained resources (relations, indices).
void	destroy() Destroy any logically contained resources (relations, indices).
protected Properties	getBareProperties() Return the Properties object without wrapping it.
int	getChunkCapacity() Deprecated. by BOp annotations.
int	getChunkOfChunksCapacity() Deprecated. by BOp annotations.
long	getChunkTimeout() Deprecated. by BOp annotations.
protected Long	getCommitTime() The commit time from which a read-only view was materialized (if known) and otherwise null.
ILocatableResource	getContainer() Return the container.
String	getContainerNamespace() The identifier for the containing resource.
ExecutorService	getExecutorService()
int	getFullyBufferedReadThreshold() Deprecated. by BOp annotations.
IIndexManager	getIndexManager() Return the object used to locate indices, relations, and relation containers and to execute operations on those resources.
int	getMaxParallelSubqueries() Deprecated. by BOp annotations.
String	getNamespace() The identifying namespace.
Properties	getProperties() Wrap and return the properties specified to the ctor.
protected String	getProperty(String localName, String defaultValue) Resolve the property value using the IIndexManager, the namespace of the resource, and the Properties instance to be tested as hidden parameters.
protected <T> T	getProperty(String name, String defaultValue, IValidator<T> validator) Resolves, parses, and validates the property value.
long	getTimestamp() The timestamp associated with the view of the resource.
AbstractResource<E>	init() The default implementation only logs the event.
boolean	isForceSerialExecution() Deprecated. by BOp annotations.
String	toString() The class name, timestamp and namespace for the relation view.
protected void	unlock(IResourceLock resourceLock) Release the lock.

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final transient org.apache.log4j.Logger log

Constructor Detail

AbstractResource

protected AbstractResource(IIndexManager indexManager,
                           String namespace,
                           Long timestamp,
                           Properties properties)

Method Detail

getChunkOfChunksCapacity

public final int getChunkOfChunksCapacity()

Deprecated. by BOp annotations.

The capacity of the buffers accumulating chunks from concurrent producers.

See Also:

AbstractResource.Options.CHUNK_OF_CHUNKS_CAPACITY

getChunkCapacity

public final int getChunkCapacity()

Deprecated. by BOp annotations.

The target chunk size.

See Also:

AbstractResource.Options.CHUNK_CAPACITY

getChunkTimeout

public final long getChunkTimeout()

Deprecated. by BOp annotations.

The timeout in milliseconds that the BlockingBuffer will wait for another chunk to combine with the current chunk before returning the current chunk. This may be ZERO (0) to disable the chunk combiner.

See Also:

AbstractResource.Options.CHUNK_TIMEOUT

getFullyBufferedReadThreshold

public int getFullyBufferedReadThreshold()

Deprecated. by BOp annotations.

If the estimated range count for an IAccessPath.iterator(int, int) is LTE this threshold then do a fully buffered (synchronous) read. Otherwise we will do an asynchronous read.

See Also:

AbstractResource.Options.FULLY_BUFFERED_READ_THRESHOLD

isForceSerialExecution

public boolean isForceSerialExecution()

Deprecated. by BOp annotations.

When true, rule sets will be forced to execute sequentially even when they are not flagged as a sequential program.

See Also:

AbstractResource.Options.FORCE_SERIAL_EXECUTION

getMaxParallelSubqueries

public int getMaxParallelSubqueries()

Deprecated. by BOp annotations.

The maximum #of subqueries for the first join dimension that will be issued in parallel. Use ZERO(0) to avoid submitting tasks to the ExecutorService entirely and ONE (1) to submit a single task at a time to the ExecutorService.

See Also:

AbstractResource.Options.MAX_PARALLEL_SUBQUERIES

getNamespace

public final String getNamespace()

Description copied from interface: ILocatableResource

The identifying namespace.

Specified by:

getNamespace in interface ILocatableResource<E>

getContainerNamespace

public final String getContainerNamespace()

Description copied from interface: ILocatableResource

The identifier for the containing resource.

Specified by:

getContainerNamespace in interface ILocatableResource<E>

Returns:

The identifier of the containing resource -or- null if there is no containing resource.

getContainer

public ILocatableResource getContainer()

Return the container.

Returns:

The container -or- null if there is no container.

getTimestamp

public final long getTimestamp()

Description copied from interface: ILocatableResource

The timestamp associated with the view of the resource.

Specified by:

getTimestamp in interface ILocatableResource<E>

getCommitTime

protected Long getCommitTime()

The commit time from which a read-only view was materialized (if known) and otherwise null.

See Also:

https://sourceforge.net/apps/trac/bigdata/ticket/266

getProperties

public final Properties getProperties()

Wrap and return the properties specified to the ctor. Wrapping the Properties object prevents inadvertent side-effects.

getBareProperties

protected final Properties getBareProperties()

Return the Properties object without wrapping it. This method can be used in those cases where you need to access non-String property values. The caller is responsible for avoiding mutation to the returned Properties object.

Note: This explicitly does NOT wrap the properties. Doing so makes it impossible to access the default properties using Hashtable#get(), which in turn means that we can not access non-String objects which have been materialized from the GRS in the Properties. This does introduce some potential for side-effects between read-only instances of the same resource view which share the same properties object.

getIndexManager

public IIndexManager getIndexManager()

Return the object used to locate indices, relations, and relation containers and to execute operations on those resources.

Note: For scale-out, this is always the federation's index manager NOT the data service local index manager. This is an artifact of how we resolve the metadata for the relation against the global row store.

Returns:

The IIndexManager.

TODO:

If we support the notion of a "relation shard" then this could become the shard's data service local index manager in that instance but, regardless, we would need a means to resolve the metadata for the relation against the federation's index manager

getExecutorService

public final ExecutorService getExecutorService()

toString

public String toString()

The class name, timestamp and namespace for the relation view.

Overrides:

toString in class Object

init

public AbstractResource<E> init()

The default implementation only logs the event.

Specified by:

init in interface ILocatableResource<E>

create

public void create()

Description copied from interface: IMutableResource

Create any logically contained resources (relations, indices). There is no presumption that ILocatableResource.init() is suitable for invocation from IMutableResource.create(). Instead, you are responsible for invoking ILocatableResource.init() from this method IFF it is appropriate to reuse its initialization logic.

Specified by:

create in interface IMutableResource<E>

TODO:

Lock service supporting shared locks, leases and lease renewal, escalation of shared locks to exclusive locks, deadlock detection, and possibly a resource hierarchy. Leases should be Callable objects that are submitted by the client to its executor service so that they will renew automatically until cancelled (and will cancel automatically if not renewed).

There is existing code that could be adapted for this purpose. It might have to be adapted to support lock escalation (shared to exclusive), a resource hierarchy, and a delay queue to cancel leases that are not renewed. It would have to be wrapped up as a low-latency service and made available via the IBigdataFederation. It also needs to use a weak reference cache for the collection of resource queues so that they are GC'd rather than growing as new resources are locked and never shrinking.

If we require pre-declaration of locks, then we do not need the dependency graph since deadlocks can only arise with 2PL.

Since the service is remote it should use UUIDs to identify the lock owner(s).

The lock service would be used to bracket operations such as relation create() and destroy() and would be used to prevent those operations while a lease is held by concurrent processes with a shared lock.

Add ctor flag to create iff not found?

There needs to be a lock protocol for subclasses so that they can ensure that they are the only task running create (across the federation) and so that they can release the lock when they are done. The lock can be per the notes above, but the protocol with the subclass will require some coordinating methods.

Full transactions are another way to solve this problem.

destroy

public void destroy()

Description copied from interface: IMutableResource

Destroy any logically contained resources (relations, indices).

Specified by:

destroy in interface IMutableResource<E>

acquireExclusiveLock

protected IResourceLock acquireExclusiveLock()

Acquires an exclusive lock for the getNamespace().

Returns:

the lock.

Throws:

RuntimeException - if anything goes wrong.

See Also:

IResourceLockService

unlock

protected void unlock(IResourceLock resourceLock)

Release the lock.

Parameters:

resourceLock - The lock.

getProperty

protected String getProperty(String localName,
                             String defaultValue)

Resolve the property value using the IIndexManager, the namespace of the resource, and the Properties instance to be tested as hidden parameters.

Parameters:

globalName - The global property name.

defaultValue - The default.

Returns:

The resolved property value.

See Also:

Configuration

getProperty

protected <T> T getProperty(String name,
                            String defaultValue,
                            IValidator<T> validator)

Resolves, parses, and validates the property value.

Parameters:

name - The property name.

defaultValue - The default value.

Returns: