org.lacibus.triplestore

Class Item

java.lang.Object

org.lacibus.triplestore.Item

All Implemented Interfaces:

java.io.Serializable, java.lang.Comparable<java.lang.Object>

public class Item
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<java.lang.Object>

An item generally represents something, and can be the subject, verb, or object of a triple.

For example, one item might represent the person John Smith, and another might represent the concept of a person having a family name. A triple whose subject is the first item, whose verb is the second item, and whose object is the string "Smith" then conveys the information that John Smith's family name is "Smith".

Items do not convey meaning in themselves. There is nothing about the item representing John Smith to indicate that it represents anything or anyone in particular. The meaning can be conveyed in separate textual descriptions, such as, "The item represents the person John Smith" and by the triples in which the item appears.

Each item, apart from a few special items, is stored in a source.

Each item is uniquely identified by a combination of two numbers, one identifying the source that contains the item, and the other uniquely identifying the item within that source. For special items, the source number is zero; there is no real source with that number.

Each item has two access levels: an only-read level, which controls who can read it, and a read-or-write level, which controls who can write it (and enables anyone who can write it to read it also). Access to a triple is controlled by the access levels of the items in the triple. The access levels of the items thus provide fine-grained access control for all the data in a triple store.

An item can be locked to prevent simultaneous writes by different sessions. This also prevents simultaneous writes to triples, because writing to a triple requires its subject to be locked. The series of write actions performed while an item is locked is a transaction. When the item is unlocked, the transaction is completed, and the write actions are carried out in the item's source.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
boolean	canBeReadBy(StoreSession session) Determine whether a store session has read access
boolean	canBeWrittenBy(StoreSession session) Determine whether a store session has write access
boolean	checkLocked(StoreSession session) Check that the item is locked by a store session
int	compareTo(java.lang.Object o)
boolean	equals(Item it) Determine whether the item is equal to another item
AccessLevel	getEffectiveOnlyReadLevel(StoreSession session) Get the effective only-read level
AccessLevel	getEffectiveReadOrWriteLevel(StoreSession session) Get the effective read-or-write level
Id	getId() Get the item's identifier
long	getItemNr() Get the identification number of the item within its source
long	getSourceNr() Get the item's source number
org.lacibus.triplestore.Item.State	getState() Get the state of the item
Transaction	getTransaction() Get the transaction associated with the item.
int	hashCode()
boolean	isCurrent() Determine whether the item is current
boolean	isLocked() Determine whether the item is locked
boolean	lock(StoreSession session) Lock the item.
boolean	setOnlyReadLevel(AccessLevel level, StoreSession session) Set the item's only-read access level.
boolean	setReadOrWriteLevel(AccessLevel level, StoreSession session) Set the item's read-or-write access level.
long	summary()
java.lang.String	toString()
void	unlock(StoreSession session) Unlock the item

Methods inherited from class java.lang.Object

equals, getClass, notify, notifyAll, wait, wait, wait

Method Detail

getState

public org.lacibus.triplestore.Item.State getState()

Get the state of the item

Returns:

the state of the item

isCurrent

public boolean isCurrent()

Determine whether the item is current

Returns:

true if the state of the item is EXISTS and its source is operational (or it is a special item that has no source), and if its only-read and read-or-write access levels exist and are in connected sources, false otherwise

getSourceNr

public long getSourceNr()

Get the item's source number

Returns:

the numeric identifier of the item's source

getItemNr

public long getItemNr()

Get the identification number of the item within its source

Returns:

the numeric identifier of the item within its source

getId

public Id getId()

Get the item's identifier

Returns:

the item's identifier (which is a combination of the numeric identifier of the item's source and the numeric identifier of the item within its source).

lock

public boolean lock(StoreSession session)
             throws TripleStoreNonFatalException,
                    SourceConnectorException

Lock the item.

A transaction is started to include source connector operations involving the item while it is locked

Parameters:

session - the store session for which the item is to be locked. This session must have write access to the item. This implies that the session access level is not null, deleted, or being replaced.

Returns:

true if the item is locked successfully, false otherwise. If an exception is thrown then the item is not locked.

Throws:

TripleStoreNonFatalException

SourceConnectorException

unlock

public void unlock(StoreSession session)
            throws TripleStoreNonFatalException,
                   SourceConnectorException,
                   TripleStoreFatalException,
                   NotInOperationException

Unlock the item

The transaction that was started when the item was locked is ended.

If the session is valid, source containing the item is connected and owned by the triple store, the item is current and was locked by the session, and this method returns, then the item will no longer be locked. If it cannot be unlocked, then its source is disconnected and a source connector exception is thrown or, if this is not possible, operation of the triple store is aborted and a Fatal exception is thrown.

Parameters:

session - the store session requesting the item be unlocked.

Throws:

SourceConnectorException

NotInOperationException

TripleStoreFatalException

TripleStoreNonFatalException

checkLocked

public boolean checkLocked(StoreSession session)
                    throws TripleStoreNonFatalException

Check that the item is locked by a store session

Parameters:

session - the store session for which the check is made. If this is the session that locked the item then true is returned and no exception is thrown, even if the session is invalid. If it is not the session that locked the item, and is invalid, then an exception is thrown.

Returns:

true if the item is locked by the given session, false otherwise

Throws:

TripleStoreNonFatalException

isLocked

public boolean isLocked()
                 throws TripleStoreNonFatalException

Determine whether the item is locked

Returns:

true if the item is locked, false otherwise

Throws:

TripleStoreNonFatalException

getTransaction

public Transaction getTransaction()
                           throws TripleStoreNonFatalException

Get the transaction associated with the item.

Returns:

the transaction associated with the item if it is locked, null otherwise

Throws:

TripleStoreNonFatalException

canBeReadBy

public boolean canBeReadBy(StoreSession session)
                    throws TripleStoreNonFatalException

Determine whether a store session has read access

Parameters:

session - a store session

Returns:

whether the store session has read access to the item

Throws:

TripleStoreNonFatalException

getEffectiveOnlyReadLevel

public AccessLevel getEffectiveOnlyReadLevel(StoreSession session)
                                      throws TripleStoreNonFatalException

Get the effective only-read level

Parameters:

session - the requesting store session

Returns:

the last access level in the chain of replacements, starting with the only-read level, if the chain contains only access levels, and if the last level can be read by the requesting session, null otherwise.

Throws:

TripleStoreNonFatalException

canBeWrittenBy

public boolean canBeWrittenBy(StoreSession session)
                       throws TripleStoreNonFatalException

Determine whether a store session has write access

Parameters:

session - a session

Returns:

whether the session has write access to the item

Throws:

TripleStoreNonFatalException

getEffectiveReadOrWriteLevel

public AccessLevel getEffectiveReadOrWriteLevel(StoreSession session)
                                         throws TripleStoreNonFatalException

Get the effective read-or-write level

Parameters:

session - the requesting store session

Returns:

the last access level in the chain of replacements, starting with the read-or-write level, if the chain contains only access levels, and if the last level can be read by the requesting session, null otherwise.

Throws:

TripleStoreNonFatalException

setOnlyReadLevel

public boolean setOnlyReadLevel(AccessLevel level,
                                StoreSession session)
                         throws TripleStoreNonFatalException,
                                SourceConnectorException,
                                NotInOperationException

Set the item's only-read access level.

The item must not be a special item of the triple store, or have been deleted.

The item is written to its source by this operation.

Parameters:

level - the only-read access level to be set. This level must be valid, and must not be being replaced.

session - the store session requesting the change of level. The item must be locked by this session for the operation to succeed, and it must have read access to the new only-read access level.

Returns:

true if the level was set successfully, false otherwise

Throws:

NotInOperationException

TripleStoreNonFatalException

SourceConnectorException

setReadOrWriteLevel

public boolean setReadOrWriteLevel(AccessLevel level,
                                   StoreSession session)
                            throws NotInOperationException,
                                   TripleStoreNonFatalException,
                                   TripleStoreFatalException,
                                   SourceConnectorException

Set the item's read-or-write access level.

The item must not be a special item of the triple store, or have been deleted

The item is written to the sourcee by this operation.

Parameters:

level - the read-or-write access level to be set. This level must be valid, and must not be being replaced.

session - the session requesting the change of level. The item must be locked by this session for the operation to succeed and the session access level must be superior to the new read-or-write level so that the session will continue to have write access. The session must have read access to the new level.

Returns:

true if the level was set successfully, false otherwise

Throws:

NotInOperationException

TripleStoreNonFatalException

TripleStoreFatalException

SourceConnectorException

equals

public boolean equals(Item it)

Determine whether the item is equal to another item

Parameters:

it - another item. If this is null, false is returned.

Returns:

whether the item is equal to another item

compareTo

public int compareTo(java.lang.Object o)

Specified by:

compareTo in interface java.lang.Comparable<java.lang.Object>

summary

public long summary()

Returns:

a long integer that summarises the item

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object