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	commit() commit ALL records on this blackboard to storages (if any) and release resources.
void	commit(java.lang.String id) All changes are written to the storages before the record is removed.
Record	copyRecord(java.lang.String id, java.lang.String newId) Creates a copy of the record with a new Id and returns the new record.
Record	create(java.lang.String id) Creates a new record with a given ID in memory, but only if it doesn't exist there yet, if it does, then nothing happens and the existing record is returned.
Record	filterRecord(Record record, java.lang.String filterName) Filter record metadata.
byte[]	getAttachment(java.lang.String id, java.lang.String name) Gets the attachment.
java.io.File	getAttachmentAsFile(java.lang.String id, java.lang.String name) Gets attachment as file.
java.io.InputStream	getAttachmentAsStream(java.lang.String id, java.lang.String name) Gets the attachment as stream.
DataFactory	getDataFactory()
java.io.Serializable	getGlobalNote(java.lang.String name) Gets the global note.
AnyMap	getMetadata(java.lang.String id) Shortcut for getRecord(String) + Record.getMetadata().
Record	getRecord(java.lang.String id) Gets the record for the given Id.
Record	getRecord(java.lang.String id, java.lang.String filterName) Gets the filtered record.
java.io.Serializable	getRecordNote(java.lang.String id, java.lang.String name) Gets the record note.
boolean	hasAttachment(java.lang.String id, java.lang.String name) Checks for attachment.
boolean	hasGlobalNote(java.lang.String name) Checks for global note.
boolean	hasRecordNote(java.lang.String id, java.lang.String name) Checks for record note.
void	invalidate() remove ALL records from blackboard and release all associated resources.
void	invalidate(java.lang.String id) The record is removed from the blackboard.
Record	load(java.lang.String id) Loads record data for the given ID from persistence (or prepare it to be loaded).
void	removeAttachment(java.lang.String id, java.lang.String name) Removes the attachment.
void	removeRecord(java.lang.String id) remove record completely from blackboard and persistence.
void	setAttachment(java.lang.String id, java.lang.String name, byte[] attachment) Sets the attachment.
void	setAttachmentFromFile(java.lang.String id, java.lang.String name, java.io.File attachmentFile) Sets attachment from file.
void	setAttachmentFromStream(java.lang.String 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	setRecord(Record record) Stores a record on the blackboard.
void	setRecordNote(java.lang.String id, java.lang.String name, java.io.Serializable object) Sets the record note.
void	synchronizeRecord(Record record) Synchronize: copy all existing attributes from the incoming record to the blackboard record with the same ID.

Method Detail

getDataFactory

DataFactory getDataFactory()

Returns:

the data factory used by this blackboard to create records.

getRecord

Record getRecord(java.lang.String 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(String). Depending on the blackboard implementation, attachments may or may not be included in the returned record.

Parameters:

id - the id

Returns:

the record

Throws:

BlackboardAccessException - the blackboard access exception

getMetadata

AnyMap getMetadata(java.lang.String id)
                   throws BlackboardAccessException

Shortcut for getRecord(String) + Record.getMetadata(). If getRecord(String) would yield null, this method yields null, too.

Parameters:

id - the id

Returns:

the record metadata

Throws:

BlackboardAccessException - the blackboard access exception

getRecord

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

Gets the filtered record. No attachments will be included.

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 metadata. Attachments will not be included in the filtered record.

Parameters:

record - the record

filterName - the filter name

Returns:

the record

Throws:

RecordFilterNotFoundException - the record filter not found exception

setRecord

void setRecord(Record record)
               throws BlackboardAccessException

Stores a record on the blackboard. If a record with the same Id already exists, it will be replaced.

Parameters:

record - the record

Throws:

BlackboardAccessException - the blackboard access exception

copyRecord

Record copyRecord(java.lang.String id,
                  java.lang.String newId)
                  throws BlackboardAccessException

Creates a copy of the record with a new Id and returns the new record. Attachments are not copied.

Parameters:

id - the id

newId - the id of the copy

Returns:

the copied record.

Throws:

BlackboardAccessException - the blackboard access exception

synchronizeRecord

void synchronizeRecord(Record record)
                       throws BlackboardAccessException

Synchronize: copy all existing attributes from the incoming record to the blackboard record with the same ID.

Parameters:

record - the record

Throws:

BlackboardAccessException - the blackboard access exception

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(java.lang.String id)

Creates a new record with a given ID in memory, but only if it doesn't exist there yet, if it does, then nothing happens and the existing record is returned. This method is agnostic to the persistence 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(java.lang.String 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:

a newly created or existing record, or in some cases null if record isn't found (implementation specific)

Throws:

BlackboardAccessException - the blackboard access exception

commit

void commit(java.lang.String 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(java.lang.String 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

removeRecord

void removeRecord(java.lang.String id)

remove record completely from blackboard and persistence.

Parameters:

id - record id

hasAttachment

boolean hasAttachment(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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(java.lang.String 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