org.lacibus.triplesource

Class SourceConnector

java.lang.Object

org.lacibus.triplesource.SourceConnector

All Implemented Interfaces:

java.io.Serializable

Direct Known Subclasses:

FileSourceConnector

public abstract class SourceConnector
extends java.lang.Object
implements java.io.Serializable

A connector to a source of items and triples.

Each source is identified by a unique long integer.

Positive integers are used for private sources, negative integers are used for shared sources, and zero is used for the virtual source containing special items.

There is a maximum and a minimum value set for source numbers. All integers outside this range are reserved to be allocated uses at a future time.

Within a source, each item is identified by a unique reference that is a long integer, and each triple is identified by a unique reference that is a long integer. These are the numeric identifiers of the items and triples within their sources. (The identifier spaces are separate. An item and a triple can have the same numeric identifier.)

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	SourceConnector.IdAndTrans Numeric item identifier and transaction returned when an item is added

Field Summary

Fields

Modifier and Type	Field and Description
static long	adminLevelItemNr The numeric identifier of the item that represents the administration access level of the source.
static long	adminLevelTripleNr The numeric identifier of the triple that defines the administration access level of the source.
static long	sourceItemNr The numeric identifier of the source item.

Method Summary

Modifier and Type	Method and Description
abstract SourceConnector.IdAndTrans	addItem(Id onlyReadLevelId, Id readOrWriteLevelId) Add an item
SourceConnector.IdAndTrans	addSourceItem(Id onlyReadLevelId, Id readOrWriteLevelId) Add an item if the source connector is operational.
abstract void	close() Close the source connector
abstract void	create() Create the source.
StoredTriple	createSourceTriple(Item subject, Item verb, Datum object, Transaction trans) Create a triple if the source connector is operational.
abstract StoredTriple	createTriple(Item subject, Item verb, Datum object, Transaction trans) Create a triple
void	endSourceTransaction(Transaction trans) End a transaction if the source connector is operational.
abstract void	endTransaction(Transaction trans) End a transaction.
abstract Datum	getBinaryTripleObject(long tripleNr) Get a stored triple's binary object
SourceConnectorClient	getClient()
java.io.File	getLocalDir()
Datum	getSourceBinaryTripleObject(long tripleNr) Get a stored triple's binary object if the source connector is operational.
long	getSourceNr()
Datum	getSourceTextTripleObject(long tripleNr) Get a stored triple's text object if the source connector is operational.
java.io.File	getSpecFile()
java.lang.String	getSpecFilePath()
abstract java.lang.Exception	getTerminator() Return an exception that caused connector operation to abort.
abstract Datum	getTextTripleObject(long tripleNr) Get a stored triple's text object
static boolean	isDomainSourceNr(long nr) Determine whether a source number is that of a domain source
static boolean	isInstallationSourceNr(long nr) Determine whether a source number is that of an installation-specific source
boolean	isOperational()
boolean	isOwner()
static boolean	isRegisteredSourceNr(long nr) Determine whether a source number is that of a registered source
abstract void	load() Load items and triples into a triple store from the connector, but without adding the items to the triple store's index.
void	log(java.lang.String message) Create a log entry
void	makeOperational() Make the connector operational
abstract void	removeItem(long itemNr, Transaction trans) Remove an item from the source
void	removeSourceItem(long itemNr, Transaction trans) Remove an item from the source if the source connector is operational.
void	removeSourceTriple(long tripleNr, Transaction trans) Note that a triple is removed from the source if the source connector is operational.
abstract void	removeTriple(long tripleNr, Transaction trans) Note that a triple is removed from the source.
StoredTriple	replaceSourceTriple(Triple triple, Datum newObject, Transaction trans) Replace a triple in the source by a new triple with the same subject and verb, but with a new object and a new numeric identifier, if the source connector is operational.
abstract StoredTriple	replaceTriple(Triple triple, Datum newObject, Transaction trans) Replace a triple in the source by a new triple with the same subject and verb, but with a new object and a new numeric identifier
abstract void	simulateIoError() Simulate an I/O error for testing purposes
abstract boolean	sourceExists() Determine whether the source exists or must be created.
Transaction	startSourceTransaction() Start a new transaction if the source connector is operational.
abstract Transaction	startTransaction() Start a new transaction.
void	stopOperation() Stop operation of the source connector
abstract void	updateItem(long itemNr, Id onlyReadLevelId, Id readOrWriteLevelId, Transaction trans) Update an item in the source
void	updateSourceItem(long itemNr, Id onlyReadLevelId, Id readOrWriteLevelId, Transaction trans) Update an item in the source if the source connector is operational.

Methods inherited from class java.lang.Object

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

Field Detail

sourceItemNr

public static final long sourceItemNr

The numeric identifier of the source item. Each source contains a source item, and they all have the same numeric identifier. The source item is locked whenever changes are made to named items in the source.

See Also:

Constant Field Values

adminLevelItemNr

public static final long adminLevelItemNr

The numeric identifier of the item that represents the administration access level of the source. Each source has an administration access level, and they are all represented by items with the same numeric identifier. This item is the subject and object of an access level triple. When the source has been created, a user who has access at its administration level can perform various administration functions.

See Also:

Constant Field Values

adminLevelTripleNr

public static final long adminLevelTripleNr

The numeric identifier of the triple that defines the administration access level of the source.

See Also:

Constant Field Values

Method Detail

isInstallationSourceNr

public static boolean isInstallationSourceNr(long nr)

Determine whether a source number is that of an installation-specific source

Parameters:

nr - a source number

Returns:

whether the source number is that of an installation-specific source

isDomainSourceNr

public static boolean isDomainSourceNr(long nr)

Determine whether a source number is that of a domain source

Parameters:

nr - a source number

Returns:

whether the source number is that of a domain source

isRegisteredSourceNr

public static boolean isRegisteredSourceNr(long nr)

Determine whether a source number is that of a registered source

Parameters:

nr - a source number

Returns:

whether the source number is that of a registered source

Throws:

java.io.IOException

getClient

public SourceConnectorClient getClient()

Returns:

the client of the source connector

getSourceNr

public long getSourceNr()

Returns:

the numeric identifier of the source that the connector is connected to

isOwner

public boolean isOwner()

Returns:

whether the source connector is connecting the source's owner to the source

getLocalDir

public java.io.File getLocalDir()

getSpecFile

public java.io.File getSpecFile()

getSpecFilePath

public java.lang.String getSpecFilePath()
                                 throws java.io.IOException

Throws:

java.io.IOException

isOperational

public boolean isOperational()

Returns:

whether the source connector is operational

makeOperational

public void makeOperational()

Make the connector operational

sourceExists

public abstract boolean sourceExists()
                              throws SourceConnectorException

Determine whether the source exists or must be created. If this method returns true, then the caller should assume that the source has been created. If it returns false, then the caller should create it.

Returns:

true if the source exists, or creation of the source has at least been started.

Throws:

SourceConnectorException

create

public abstract void create()
                     throws SourceConnectorException,
                            TripleStoreNonFatalException

Create the source.

A new source is created.

A source must be created, or loaded, but not both, before it can be used.

A source is created with a source item and a source administration access level. The only-read level of the source item is the lowest access level, and its read-or-write level is the highest access level.The only-read level of the source administration access level is the lowest access level, and it is its own read-or-write level.

Throws:

SourceConnectorException

TripleStoreNonFatalException

load

public abstract void load()
                   throws SourceConnectorException,
                          TripleStoreNonFatalException

Load items and triples into a triple store from the connector, but without adding the items to the triple store's index.

Invoked by the loadFromSource() method to apply a set of deltas that add items and triples in the source to the invoking triple store. This part of the load process is specific to the source. The subsequent part, in which the loaded items are indexed, is handled by the loadFromSource() method.

Note that the deltas may contain deletions as well as additions, and must be applied in order. This implies that the connector must apply deltas adding the items referenced by a triple before applying the delta that adds the triple. However, triples setting access level superiority permissions can be loaded before the triples defining the access levels concerned.

A source must be created, or loaded, but not both, before it can be used.

Throws:

SourceConnectorException

TripleStoreNonFatalException

startSourceTransaction

public Transaction startSourceTransaction()
                                   throws SourceConnectorException

Start a new transaction if the source connector is operational.

Every write operation is associated with a transaction. It is not guaranteed that all writes for a transaction will be performed, or none. What is guaranteed is that, if there is a system failure, only records resulting from completed transactions will be re-loaded when the system re-starts.

A transaction is associated with an item, which must be from the source that this connector connects to, and must have been locked before the transaction is started. The only write operations associated with the transaction are write operations on the item, or on triples of which it is the subject.

Returns:

a newly-started transaction, or null if a transaction could not be started/

Throws:

SourceConnectorException

startTransaction

public abstract Transaction startTransaction()
                                      throws SourceConnectorException

Start a new transaction.

Every write operation is associated with a transaction. It is not guaranteed that all writes for a transaction will be performed, or none. What is guaranteed is that, if there is a system failure, only records resulting from completed transactions will be re-loaded when the system re-starts.

A transaction is associated with an item, which must be from the source that this connector connects to, and must have been locked before the transaction is started. The only write operations associated with the transaction are write operations on the item, or on triples of which it is the subject.

Returns:

a newly-started transaction, or null if a transaction could not be started/

Throws:

SourceConnectorException

endSourceTransaction

public void endSourceTransaction(Transaction trans)
                          throws SourceConnectorException

End a transaction if the source connector is operational.

Parameters:

trans - a transaction to be ended

Throws:

SourceConnectorException

endTransaction

public abstract void endTransaction(Transaction trans)
                             throws SourceConnectorException

End a transaction.

Parameters:

trans - a transaction to be ended

Throws:

SourceConnectorException

addSourceItem

public SourceConnector.IdAndTrans addSourceItem(Id onlyReadLevelId,
                                                Id readOrWriteLevelId)
                                         throws SourceConnectorException

Add an item if the source connector is operational.

Parameters:

onlyReadLevelId - the identifier of the item representing the only-read access level that the item is to have

readOrWriteLevelId - the identifier of the item representing the read-or-write access level that the item is to have

Returns:

a numeric item identifier and transaction. The identifier is a newly-assigned numeric identifier that identifies a new item that has been added to the source. The transaction is a newly started transaction whose first operation is the addition of the item.

Throws:

SourceConnectorException

TripleStoreNonFatalException

addItem

public abstract SourceConnector.IdAndTrans addItem(Id onlyReadLevelId,
                                                   Id readOrWriteLevelId)
                                            throws SourceConnectorException

Add an item

Parameters:

onlyReadLevelId - the identifier of the item representing the only-read access level that the item is to have

readOrWriteLevelId - the identifier of the item representing the read-or-write access level that the item is to have

Returns:

a numeric item identifier and transaction. The identifier is a newly-assigned numeric identifier that identifies a new item that has been added to the source. The transaction is a newly started transaction whose first operation is the addition of the item.

Throws:

SourceConnectorException

TripleStoreNonFatalException

updateSourceItem

public void updateSourceItem(long itemNr,
                             Id onlyReadLevelId,
                             Id readOrWriteLevelId,
                             Transaction trans)
                      throws SourceConnectorException,
                             TripleStoreNonFatalException

Update an item in the source if the source connector is operational.

Parameters:

itemNr - the numeric identifier of the item in the source

onlyReadLevelId - the identifier of the item representing the only-read access level that the item is to have

readOrWriteLevelId - the identifier of the item representing the read-or-write access level that the item is to have

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

TripleStoreNonFatalException

updateItem

public abstract void updateItem(long itemNr,
                                Id onlyReadLevelId,
                                Id readOrWriteLevelId,
                                Transaction trans)
                         throws SourceConnectorException,
                                TripleStoreNonFatalException

Update an item in the source

Parameters:

itemNr - the numeric identifier of the item in the source

onlyReadLevelId - the identifier of the item representing the only-read access level that the item is to have

readOrWriteLevelId - the identifier of the item representing the read-or-write access level that the item is to have

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

TripleStoreNonFatalException

removeSourceItem

public void removeSourceItem(long itemNr,
                             Transaction trans)
                      throws SourceConnectorException,
                             TripleStoreNonFatalException

Remove an item from the source if the source connector is operational.

Parameters:

itemNr - the numeric identifier of the item in the source

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

TripleStoreNonFatalException

removeItem

public abstract void removeItem(long itemNr,
                                Transaction trans)
                         throws SourceConnectorException,
                                TripleStoreNonFatalException

Remove an item from the source

Parameters:

itemNr - the numeric identifier of the item in the source

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

TripleStoreNonFatalException

createSourceTriple

public StoredTriple createSourceTriple(Item subject,
                                       Item verb,
                                       Datum object,
                                       Transaction trans)
                                throws SourceConnectorException,
                                       TripleStoreNonFatalException

Create a triple if the source connector is operational.

Parameters:

subject - the triple's subject

verb - the triple's verb

object - the triple's object

trans - the transaction of which this operation is a part

Returns:

the newly-created triple

Throws:

SourceConnectorException

TripleStoreNonFatalException

createTriple

public abstract StoredTriple createTriple(Item subject,
                                          Item verb,
                                          Datum object,
                                          Transaction trans)
                                   throws SourceConnectorException,
                                          TripleStoreNonFatalException

Create a triple

Parameters:

subject - the triple's subject

verb - the triple's verb

object - the triple's object

trans - the transaction of which this operation is a part

Returns:

the newly-created triple

Throws:

SourceConnectorException

TripleStoreNonFatalException

replaceSourceTriple

public StoredTriple replaceSourceTriple(Triple triple,
                                        Datum newObject,
                                        Transaction trans)
                                 throws SourceConnectorException,
                                        TripleStoreNonFatalException

Replace a triple in the source by a new triple with the same subject and verb, but with a new object and a new numeric identifier, if the source connector is operational.

Parameters:

triple - the triple to be replaced

newObject - the triple's new object

trans - the transaction of which this operation is a part

Returns:

a new triple, with the previous subject and verb, the new object, and a new numeric identifier, or null if the triple can not be found

Throws:

SourceConnectorException

TripleStoreNonFatalException

replaceTriple

public abstract StoredTriple replaceTriple(Triple triple,
                                           Datum newObject,
                                           Transaction trans)
                                    throws SourceConnectorException,
                                           TripleStoreNonFatalException

Replace a triple in the source by a new triple with the same subject and verb, but with a new object and a new numeric identifier

Parameters:

triple - the triple to be replaced

newObject - the triple's new object

trans - the transaction of which this operation is a part

Returns:

a new triple, with the previous subject and verb, the new object, and a new numeric identifier, or null if the triple can not be found

Throws:

SourceConnectorException

TripleStoreNonFatalException

getSourceTextTripleObject

public Datum getSourceTextTripleObject(long tripleNr)
                                throws SourceConnectorException,
                                       TripleStoreNonFatalException

Get a stored triple's text object if the source connector is operational.

Parameters:

tripleNr - the numeric identifier in its source of a stored triple

Returns:

the triple's object

Throws:

SourceConnectorException

TripleStoreNonFatalException

getTextTripleObject

public abstract Datum getTextTripleObject(long tripleNr)
                                   throws SourceConnectorException,
                                          TripleStoreNonFatalException

Get a stored triple's text object

Parameters:

tripleNr - the numeric identifier in its source of a stored triple

Returns:

the triple's object

Throws:

SourceConnectorException

TripleStoreNonFatalException

getSourceBinaryTripleObject

public Datum getSourceBinaryTripleObject(long tripleNr)
                                  throws SourceConnectorException,
                                         TripleStoreNonFatalException

Get a stored triple's binary object if the source connector is operational.

Parameters:

tripleNr - the numeric identifier in its source of a stored triple

Returns:

the triple's object

Throws:

SourceConnectorException

TripleStoreNonFatalException

getBinaryTripleObject

public abstract Datum getBinaryTripleObject(long tripleNr)
                                     throws SourceConnectorException,
                                            TripleStoreNonFatalException

Get a stored triple's binary object

Parameters:

tripleNr - the numeric identifier in its source of a stored triple

Returns:

the triple's object

Throws:

SourceConnectorException

TripleStoreNonFatalException

removeSourceTriple

public void removeSourceTriple(long tripleNr,
                               Transaction trans)
                        throws SourceConnectorException

Note that a triple is removed from the source if the source connector is operational. The triple's underlying resources (for example, a file containing its object) are not deleted until the end of the transaction, so that the triple can be reinstated if the transaction does not complete.

Parameters:

tripleNr - the numeric identifier within the source of the triple to be removed

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

removeTriple

public abstract void removeTriple(long tripleNr,
                                  Transaction trans)
                           throws SourceConnectorException

Note that a triple is removed from the source. The triple's underlying resources (for example, a file containing its object) are not deleted until the end of the transaction, so that the triple can be reinstated if the transaction does not complete.

Parameters:

tripleNr - the numeric identifier within the source of the triple to be removed

trans - the transaction of which this operation is a part

Throws:

SourceConnectorException

stopOperation

public void stopOperation()
                   throws SourceConnectorException

Stop operation of the source connector

Throws:

SourceConnectorException

close

public abstract void close()

Close the source connector

getTerminator

public abstract java.lang.Exception getTerminator()

Return an exception that caused connector operation to abort.

If an exception is thrown in the course of background processing then operation of the connector is aborted and the exception is stored.

Returns:

the Exception that aborted operation

simulateIoError

public abstract void simulateIoError()

Simulate an I/O error for testing purposes

log

public void log(java.lang.String message)

Create a log entry

Parameters:

message - a message to be logged