org.eclipse.smila.blackboard
Interface Blackboard

All Known Implementing Classes:

PersistingBlackboardImpl, TransientBlackboardImpl

public interface Blackboard

The Blackboard is a container for a set of records that are processed in a single step, e.g. to add a crawled record to SMILA in connectivity or to process a single queue message. The blackboard can be connected to storage services (binary storage, record storage) so that existing versions of records can be loaded before the processing starts and the result records can be persisted afterwards. However, a blackboard can also be just "transient", i.e. not connected to any storage services. Then all record data is lost after the processing is finished.

Method Summary

void	addAnnotation(Id id, Path path, java.lang.String name, Annotation annotation) Adds the annotation.
void	addLiteral(Id id, Path path, Literal value) Adds the value.
void	commit() commit ALL records on this blackboard to storages (if any) and release resources.
void	commit(Id id) All changes are written to the storages before the record is removed.
Record	create(Id id) Creates a new record with a given ID in memory, but only if it doesnt exist there yet, if it does, then nothing happens and the existing record is returned.
Annotation	createAnnotation(Id id) Creates the annotation.
Literal	createLiteral(Id id) Creates the literal.
Record	filterRecord(Record record, java.lang.String filterName) Filter record.
Annotation	getAnnotation(Id id, Path path, java.lang.String name) Gets the first annotation if it exists.
java.util.Iterator<java.lang.String>	getAnnotationNames(Id id, Path path) Gets the annotation names.
java.util.List<Annotation>	getAnnotations(Id id, Path path, java.lang.String name) Gets the annotations.
byte[]	getAttachment(Id id, java.lang.String name) Gets the attachment.
java.io.File	getAttachmentAsFile(Id id, java.lang.String name) Gets attachment as file.
java.io.InputStream	getAttachmentAsStream(Id id, java.lang.String name) Gets the attachment as stream.
java.util.Iterator<java.lang.String>	getAttributeNames(Id id) Returns iterator over attributes names by given record id.
java.util.Iterator<java.lang.String>	getAttributeNames(Id id, Path path) Returns iterator over attributes names or empty iterator if attribute was not found at the given path.
java.io.Serializable	getGlobalNote(java.lang.String name) Gets the global note.
Literal	getLiteral(Id id, Path path) Get single attribute value, index is specified in last step of path, defaults to 0.
java.util.List<Literal>	getLiterals(Id id, Path path) Get all literal attribute values of an attribute (index of last step is irrelevant) Returns empty list if attribute was not found.
int	getLiteralsSize(Id id, Path path) Returns number of attribute literals at the given path.
java.lang.String	getObjectSemanticType(Id id, Path path) Gets the metadata object semantic type.
int	getObjectSize(Id id, Path path) Gets size of metadata objects contained in this attribute.
Record	getRecord(Id id) Gets the record for the given Id.
Record	getRecord(Id id, java.lang.String filterName) Gets the record.
java.io.Serializable	getRecordNote(Id id, java.lang.String name) Gets the record note.
boolean	hasAnnotation(Id id, Path path, java.lang.String name) Checks for annotation.
boolean	hasAnnotations(Id id, Path path) Checks for annotations.
boolean	hasAttachment(Id id, java.lang.String name) Checks for attachment.
boolean	hasAttribute(Id id, Path path) Checks for attribute. index of last step is irrelevant.
boolean	hasGlobalNote(java.lang.String name) Checks for global note.
boolean	hasLiterals(Id id, Path path) Checks if attribute at the given path has literals.
boolean	hasObjects(Id id, Path path) Checks if attribute has sub metadata objects.
boolean	hasRecordNote(Id id, java.lang.String name) Checks for record note.
void	invalidate() remove ALL records from blackboard and release all associated resources.
void	invalidate(Id id) The record is removed from the blackboard.
Record	load(Id id) Loads record data for the given ID from persistence (or prepare it to be loaded).
void	removeAnnotation(Id id, Path path, java.lang.String name) Removes the annotation.
void	removeAnnotations(Id id, Path path) Removes the annotations.
void	removeAttachment(Id id, java.lang.String name) Removes the attachment.
void	removeLiteral(Id id, Path path) Removes the value.
void	removeLiterals(Id id, Path path) Removes the values.
void	removeObject(Id id, Path path) Removes sub-objects specified by index in last step.
void	removeObjects(Id id, Path path) Removes all sub-objects of specified attribute.
void	setAnnotation(Id id, Path path, java.lang.String name, Annotation annotation) Sets the annotation.
void	setAnnotations(Id id, Path path, java.lang.String name, java.util.List<Annotation> annotations) Sets the annotations.
void	setAttachment(Id id, java.lang.String name, byte[] attachment) Sets the attachment.
void	setAttachmentFromFile(Id id, java.lang.String name, java.io.File attachmentFile) Sets attachment from file.
void	setAttachmentFromStream(Id id, java.lang.String name, java.io.InputStream attachmentStream) Sets the attachment from stream.
void	setGlobalNote(java.lang.String name, java.io.Serializable object) Sets the global note.
void	setLiteral(Id id, Path path, Literal value) Sets the value.
void	setLiterals(Id id, Path path, java.util.List<Literal> values) Sets the values.
void	setObjectSemanticType(Id id, Path path, java.lang.String typename) Sets the object semantic type.
void	setRecord(Record record) Adds a record to the blackboard.
void	setRecordNote(Id id, java.lang.String name, java.io.Serializable object) Sets the record note.
Id	split(Id id, java.lang.String fragmentName) Creates a fragment of a given record, i.e. the record content is copied to a new ID derived from the given by adding a frament name.
void	synchronize(Record record) Synchronize.

Method Detail

commit

void commit()
            throws BlackboardAccessException

commit ALL records on this blackboard to storages (if any) and release resources. It is guaranteed that the blackboard is empty after the operation, but it throws an exception if at least one record could not be committed (e.g. written to storages) successfully. However, the implementation should try to commit as many records as possible and not stop on the first failed commit and invalidate the remaining records.

Throws:

BlackboardAccessException - at least one record could not be committed.

invalidate

void invalidate()

remove ALL records from blackboard and release all associated resources. Nothing is written to connected storage services.

create

Record create(Id id)

Creates a new record with a given ID in memory, but only if it doesnt exist there yet, if it does, then nothing happens and the existing record is returned. This method is agnostic to the persistance layer, i.e. it will not check if a record with the same ID has been persisted before. Hence, if there is a record that is persisted but not in memory and this method is called a new record is created (in memory) and a possible flowing commit will overwrite the persisted record.

Parameters:

id - the id

Returns:

the newly created or existing record.

load

Record load(Id id)
            throws BlackboardAccessException

Loads record data for the given ID from persistence (or prepare it to be loaded). Used by a client to indicate that it wants to process this record. The behavior is very implementation specific so check the the impl's doc.

Parameters:

id - the id

Returns:

TODO

Throws:

BlackboardAccessException - the blackboard access exception

setRecord

void setRecord(Record record)
               throws BlackboardAccessException

Adds a record to the blackboard.

Parameters:

record - the record

Throws:

BlackboardAccessException - the blackboard access exception

split

Id split(Id id,
         java.lang.String fragmentName)
         throws BlackboardAccessException

Creates a fragment of a given record, i.e. the record content is copied to a new ID derived from the given by adding a frament name.

Parameters:

id - the id

fragmentName - the fragment name

Returns:

the id

Throws:

BlackboardAccessException - the blackboard access exception

commit

void commit(Id id)
            throws BlackboardAccessException

All changes are written to the storages before the record is removed. The record is unlocked in the database.

Parameters:

id - the id

Throws:

BlackboardAccessException - the blackboard access exception

invalidate

void invalidate(Id id)

The record is removed from the blackboard. The record is unlocked in the database. If the record was created new (not overwritten) on this blackboard it should be removed from the storage completely.

Parameters:

id - the id

createLiteral

Literal createLiteral(Id id)
                      throws BlackboardAccessException

Creates the literal.

Parameters:

id - the id

Returns:

the literal

Throws:

BlackboardAccessException - the blackboard access exception

createAnnotation

Annotation createAnnotation(Id id)
                            throws BlackboardAccessException

Creates the annotation.

Parameters:

id - the id

Returns:

the annotation

Throws:

BlackboardAccessException - the blackboard access exception

getAttributeNames

java.util.Iterator<java.lang.String> getAttributeNames(Id id,
                                                       Path path)
                                                       throws BlackboardAccessException

Returns iterator over attributes names or empty iterator if attribute was not found at the given path.

Parameters:

id - the id

path - the path

Returns:

the attribute names

Throws:

BlackboardAccessException - the blackboard access exception

getAttributeNames

java.util.Iterator<java.lang.String> getAttributeNames(Id id)
                                                       throws BlackboardAccessException

Returns iterator over attributes names by given record id.

Parameters:

id - the id

Returns:

the attribute names

Throws:

BlackboardAccessException - the blackboard access exception

hasAttribute

boolean hasAttribute(Id id,
                     Path path)
                     throws BlackboardAccessException

Checks for attribute. index of last step is irrelevant.

Parameters:

id - the id

path - the path

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

hasLiterals

boolean hasLiterals(Id id,
                    Path path)
                    throws BlackboardAccessException

Checks if attribute at the given path has literals.

Parameters:

id - the id

path - the path

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getLiteralsSize

int getLiteralsSize(Id id,
                    Path path)
                    throws BlackboardAccessException

Returns number of attribute literals at the given path. Returns 0 if attribute was not found.

Parameters:

id - the id

path - the path

Returns:

the value size

Throws:

BlackboardAccessException - the blackboard access exception

getLiterals

java.util.List<Literal> getLiterals(Id id,
                                    Path path)
                                    throws BlackboardAccessException

Get all literal attribute values of an attribute (index of last step is irrelevant) Returns empty list if attribute was not found.

Parameters:

id - the id

path - the path

Returns:

the values

Throws:

BlackboardAccessException - the blackboard access exception

getLiteral

Literal getLiteral(Id id,
                   Path path)
                   throws BlackboardAccessException

Get single attribute value, index is specified in last step of path, defaults to 0. Returns null if attribute or literal was not found.

Parameters:

id - the id

path - the path

Returns:

the value

Throws:

BlackboardAccessException - the blackboard access exception

setLiterals

void setLiterals(Id id,
                 Path path,
                 java.util.List<Literal> values)
                 throws BlackboardAccessException

Sets the values.

Parameters:

id - the id

path - the path

values - the values

Throws:

BlackboardAccessException - the blackboard access exception

setLiteral

void setLiteral(Id id,
                Path path,
                Literal value)
                throws BlackboardAccessException

Sets the value.

Parameters:

id - the id

path - the path

value - the value

Throws:

BlackboardAccessException - the blackboard access exception

addLiteral

void addLiteral(Id id,
                Path path,
                Literal value)
                throws BlackboardAccessException

Adds the value.

Parameters:

id - the id

path - the path

value - the value

Throws:

BlackboardAccessException - the blackboard access exception

removeLiteral

void removeLiteral(Id id,
                   Path path)
                   throws BlackboardAccessException

Removes the value.

Parameters:

id - the id

path - the path

Throws:

BlackboardAccessException - the blackboard access exception

removeLiterals

void removeLiterals(Id id,
                    Path path)
                    throws BlackboardAccessException

Removes the values.

Parameters:

id - the id

path - the path

Throws:

BlackboardAccessException - the blackboard access exception

hasObjects

boolean hasObjects(Id id,
                   Path path)
                   throws BlackboardAccessException

Checks if attribute has sub metadata objects. Returns false if attribute was not found at the given path.

Parameters:

id - the id

path - the path

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getObjectSize

int getObjectSize(Id id,
                  Path path)
                  throws BlackboardAccessException

Gets size of metadata objects contained in this attribute. Returns 0 if attribute was not found at the given path.

Parameters:

id - the id

path - the path

Returns:

the object size

Throws:

BlackboardAccessException - the blackboard access exception

removeObject

void removeObject(Id id,
                  Path path)
                  throws BlackboardAccessException

Removes sub-objects specified by index in last step.

Parameters:

id - the id

path - the path

Throws:

BlackboardAccessException - the blackboard access exception

removeObjects

void removeObjects(Id id,
                   Path path)
                   throws BlackboardAccessException

Removes all sub-objects of specified attribute.

Parameters:

id - the id

path - the path

Throws:

BlackboardAccessException - the blackboard access exception

getObjectSemanticType

java.lang.String getObjectSemanticType(Id id,
                                       Path path)
                                       throws BlackboardAccessException

Gets the metadata object semantic type. Return null if attribute was not found at the given path.

Parameters:

id - the id

path - the path

Returns:

the object semantic type

Throws:

BlackboardAccessException - the blackboard access exception

setObjectSemanticType

void setObjectSemanticType(Id id,
                           Path path,
                           java.lang.String typename)
                           throws BlackboardAccessException

Sets the object semantic type.

Parameters:

id - the id

path - the path

typename - the typename

Throws:

BlackboardAccessException - the blackboard access exception

getAnnotationNames

java.util.Iterator<java.lang.String> getAnnotationNames(Id id,
                                                        Path path)
                                                        throws BlackboardAccessException

Gets the annotation names. Returns empty iterator if annotatable object was not found at the given path. Annotations of literals are accessed via the Literal object. Use null, "" or an empty attribute path to access root annotations of record. Use PathStep.ATTRIBUTE_ANNOTATION as index in final step to access the annotation of the attribute itself.

Parameters:

id - the id

path - the path

Returns:

the annotation names

Throws:

BlackboardAccessException - the blackboard access exception

hasAnnotations

boolean hasAnnotations(Id id,
                       Path path)
                       throws BlackboardAccessException

Checks for annotations. Returns false if annotatable object was not found at the given path.

Parameters:

id - the id

path - the path

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

hasAnnotation

boolean hasAnnotation(Id id,
                      Path path,
                      java.lang.String name)
                      throws BlackboardAccessException

Checks for annotation. Returns false if annotatable object was not found at the given path.

Parameters:

id - the id

path - the path

name - the name

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getAnnotations

java.util.List<Annotation> getAnnotations(Id id,
                                          Path path,
                                          java.lang.String name)
                                          throws BlackboardAccessException

Gets the annotations. Returns empty list if annotatable object was not found at the given path.

Parameters:

id - the id

path - the path

name - the name

Returns:

the annotations

Throws:

BlackboardAccessException - the blackboard access exception

getAnnotation

Annotation getAnnotation(Id id,
                         Path path,
                         java.lang.String name)
                         throws BlackboardAccessException

Gets the first annotation if it exists. Returns null if annotatable object was not found at the given path.

Parameters:

id - the id

path - the path

name - the name

Returns:

the annotation

Throws:

BlackboardAccessException - the blackboard access exception

setAnnotations

void setAnnotations(Id id,
                    Path path,
                    java.lang.String name,
                    java.util.List<Annotation> annotations)
                    throws BlackboardAccessException

Sets the annotations.

Parameters:

id - the id

path - the path

name - the name

annotations - the annotations

Throws:

BlackboardAccessException - the blackboard access exception

setAnnotation

void setAnnotation(Id id,
                   Path path,
                   java.lang.String name,
                   Annotation annotation)
                   throws BlackboardAccessException

Sets the annotation.

Parameters:

id - the id

path - the path

name - the name

annotation - the annotation

Throws:

BlackboardAccessException - the blackboard access exception

addAnnotation

void addAnnotation(Id id,
                   Path path,
                   java.lang.String name,
                   Annotation annotation)
                   throws BlackboardAccessException

Adds the annotation.

Parameters:

id - the id

path - the path

name - the name

annotation - the annotation

Throws:

BlackboardAccessException - the blackboard access exception

removeAnnotation

void removeAnnotation(Id id,
                      Path path,
                      java.lang.String name)
                      throws BlackboardAccessException

Removes the annotation.

Parameters:

id - the id

path - the path

name - the name

Throws:

BlackboardAccessException - the blackboard access exception

removeAnnotations

void removeAnnotations(Id id,
                       Path path)
                       throws BlackboardAccessException

Removes the annotations.

Parameters:

id - the id

path - the path

Throws:

BlackboardAccessException - the blackboard access exception

hasAttachment

boolean hasAttachment(Id id,
                      java.lang.String name)
                      throws BlackboardAccessException

Checks for attachment.

Parameters:

id - the id

name - the name

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getAttachment

byte[] getAttachment(Id id,
                     java.lang.String name)
                     throws BlackboardAccessException

Gets the attachment.

Parameters:

id - the id

name - the name

Returns:

the attachment

Throws:

BlackboardAccessException - the blackboard access exception

getAttachmentAsStream

java.io.InputStream getAttachmentAsStream(Id id,
                                          java.lang.String name)
                                          throws BlackboardAccessException

Gets the attachment as stream.

Parameters:

id - the id

name - the name

Returns:

the attachment as stream

Throws:

BlackboardAccessException - the blackboard access exception

getAttachmentAsFile

java.io.File getAttachmentAsFile(Id id,
                                 java.lang.String name)
                                 throws BlackboardAccessException

Gets attachment as file. Creates file containing copy of the attachment into blackboard bundle's working directory.

Parameters:

id - the id

name - the name

Returns:

File

Throws:

BlackboardAccessException - BlackboardAccessException

setAttachment

void setAttachment(Id id,
                   java.lang.String name,
                   byte[] attachment)
                   throws BlackboardAccessException

Sets the attachment.

Parameters:

id - the id

name - the name

attachment - the attachment

Throws:

BlackboardAccessException - the blackboard access exception

setAttachmentFromStream

void setAttachmentFromStream(Id id,
                             java.lang.String name,
                             java.io.InputStream attachmentStream)
                             throws BlackboardAccessException

Sets the attachment from stream.

Parameters:

id - the id

name - the name

attachmentStream - the attachment stream

Throws:

BlackboardAccessException - the blackboard access exception

setAttachmentFromFile

void setAttachmentFromFile(Id id,
                           java.lang.String name,
                           java.io.File attachmentFile)
                           throws BlackboardAccessException

Sets attachment from file.

Parameters:

id - the id

name - the name

attachmentFile - attachment file

Throws:

BlackboardAccessException - BlackboardAccessException

removeAttachment

void removeAttachment(Id id,
                      java.lang.String name)
                      throws BlackboardAccessException

Removes the attachment.

Parameters:

id - the id

name - the name

Throws:

BlackboardAccessException - the blackboard access exception

hasGlobalNote

boolean hasGlobalNote(java.lang.String name)
                      throws BlackboardAccessException

Checks for global note.

Parameters:

name - the name

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getGlobalNote

java.io.Serializable getGlobalNote(java.lang.String name)
                                   throws BlackboardAccessException

Gets the global note.

Parameters:

name - the name

Returns:

the global note

Throws:

BlackboardAccessException - the blackboard access exception

setGlobalNote

void setGlobalNote(java.lang.String name,
                   java.io.Serializable object)
                   throws BlackboardAccessException

Sets the global note.

Parameters:

name - the name

object - the object

Throws:

BlackboardAccessException - the blackboard access exception

hasRecordNote

boolean hasRecordNote(Id id,
                      java.lang.String name)
                      throws BlackboardAccessException

Checks for record note.

Parameters:

id - the id

name - the name

Returns:

true, if successful

Throws:

BlackboardAccessException - the blackboard access exception

getRecordNote

java.io.Serializable getRecordNote(Id id,
                                   java.lang.String name)
                                   throws BlackboardAccessException

Gets the record note.

Parameters:

id - the id

name - the name

Returns:

the record note

Throws:

BlackboardAccessException - the blackboard access exception

setRecordNote

void setRecordNote(Id id,
                   java.lang.String name,
                   java.io.Serializable object)
                   throws BlackboardAccessException

Sets the record note.

Parameters:

id - the id

name - the name

object - the object

Throws:

BlackboardAccessException - the blackboard access exception

synchronize

void synchronize(Record record)
                 throws BlackboardAccessException

Synchronize.

Parameters:

record - the record

Throws:

BlackboardAccessException - the blackboard access exception

getRecord

Record getRecord(Id id)
                 throws BlackboardAccessException

Gets the record for the given Id. This will first check against the memory and if not present there it will call load(Id). Hence the bahvior is hightly implementation specfic. so check the doc there.

Parameters:

id - the id

Returns:

the record

Throws:

BlackboardAccessException - the blackboard access exception

getRecord

Record getRecord(Id id,
                 java.lang.String filterName)
                 throws BlackboardAccessException,
                        RecordFilterNotFoundException

Gets the record.

Parameters:

id - the id

filterName - the filter name

Returns:

the record

Throws:

BlackboardAccessException - the blackboard access exception

RecordFilterNotFoundException - the record filter not found exception

filterRecord

Record filterRecord(Record record,
                    java.lang.String filterName)
                    throws RecordFilterNotFoundException

Filter record.

Parameters:

record - the record

filterName - the filter name

Returns:

the record

Throws:

RecordFilterNotFoundException - the record filter not found exception