org.eclipse.smila.blackboard
Interface Blackboard

All Known Implementing Classes:

BlackboardImpl

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 no data will be persisted automatically by the blackboard, the client must care about handling of the results in this case.

Nested Class Summary

static class

Blackboard.Get use as an argument in {@link #getRecord(String, CreateMode).

Method Summary

void	commit() commit ALL records on this blackboard to storages (if any) and release resources.
void	commitRecord(java.lang.String id) All changes are written to the storages before the record is removed.
Record	filterRecord(Record record, java.lang.String filterName) Filter record metadata.
Attachment	getAttachment(java.lang.String id, java.lang.String name) Gets the attachment.
byte[]	getAttachmentAsBytes(java.lang.String id, java.lang.String name) Gets the attachment.
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) Get current version of record with given ID.
Record	getRecord(java.lang.String id, Blackboard.Get mode) get a reference to the record on the blackboard.
Record	getRecord(java.lang.String id, java.lang.String filterName) Shortcut for getRecord(String) + #filterRecord(Record, String)): Gets the blackboard record and applies the named filter.
Record	getRecordCopy(java.lang.String id, boolean withAttachments) get a shallow copy of the record on the blackboard.
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	removeAll() remove all records currently stored on blackboard.
void	removeAttachment(java.lang.String id, java.lang.String name) Removes the attachment.
void	removeRecord(java.lang.String id) remove record completely from blackboard.
void	setAttachment(java.lang.String id, Attachment attachment) Sets the attachment.
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) Sets 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 attributes and attachments from the incoming record to the blackboard record with the same ID.
void	unload() remove ALL records from blackboard and release all associated resources.
void	unloadRecord(java.lang.String id) The record is removed from the blackboard.

Method Detail

getDataFactory

DataFactory getDataFactory()

Returns:

the data factory used by this blackboard to create records.

getRecord

Record getRecord(java.lang.String id,
                 Blackboard.Get mode)
                 throws BlackboardAccessException

get a reference to the record on the blackboard. See documentation of the values of Blackboard.Get for details on the mode parameter.

Parameters:

id - the id

mode - configure behavior of method.

Returns:

the newly created or existing record.

Throws:

BlackboardAccessException

getRecord

Record getRecord(java.lang.String id)
                 throws BlackboardAccessException

Get current version of record with given ID. Same as getRecord(String, Get) with Blackboard.Get.EXISTING. This method is usually the correct one to use in pipelets or workers to process a record.

Parameters:

id - the id

Returns:

the record if it exists on blackboard or in record storage (if available), else null.

Throws:

BlackboardAccessException - error accessing attached storages

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 if the record exists on blackboard or in storage, else null.

Throws:

BlackboardAccessException - error accessing attached storages

getRecord

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

Shortcut for getRecord(String) + #filterRecord(Record, String)): Gets the blackboard record and applies the named filter.

Parameters:

id - the id

filterName - the filter name

Returns:

the filtered record metadata if the record exists on blackboard or in storage, else null.

Throws:

BlackboardAccessException - error accessing storages for reading the record

RecordFilterNotFoundException - named record filter does not exist

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 - named record filter does not exist

getRecordCopy

Record getRecordCopy(java.lang.String id,
                     boolean withAttachments)
                     throws BlackboardAccessException

get a shallow copy of the record on the blackboard.

Parameters:

id - the id

Returns:

the newly created or existing record.

Throws:

BlackboardAccessException

setRecord

void setRecord(Record record)
               throws BlackboardAccessException

Sets a record on the blackboard. If a record with the same ID already exists, it will be replaced. If the new record has attachment and a binary storage is attached to the blackboard, the attachments will be stored in binary storage and removed from memory.

Parameters:

record - the record

Throws:

BlackboardAccessException - error accessing storages for reading the record or writing attachments

synchronizeRecord

void synchronizeRecord(Record record)
                       throws BlackboardAccessException

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

Parameters:

record - the record

Throws:

BlackboardAccessException - error accessing storages for reading the record or writing attachments

removeRecord

void removeRecord(java.lang.String id)

remove record completely from blackboard. If storages are attached, the record data is removed from storages when commit() or commitRecord(String) is called.

Parameters:

id - record id

removeAll

void removeAll()

remove all records currently stored on blackboard. If storages are attached, the record data is removed from storages when commit() or commitRecord(String) is called.

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 the record exists and has the named attachment. Else false.

Throws:

BlackboardAccessException - error accessing storages for check

getAttachment

Attachment getAttachment(java.lang.String id,
                         java.lang.String name)
                         throws BlackboardAccessException

Gets the attachment.

Parameters:

id - the id

name - the name

Returns:

the attachment, or null if record does not exist or does not have the attachment

Throws:

BlackboardAccessException - error accessing storages for reading the record or attachment

getAttachmentAsBytes

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

Gets the attachment.

Parameters:

id - the id

name - the name

Returns:

the attachment, or null if record does not exist or does not have the attachment

Throws:

BlackboardAccessException - error accessing storages for reading the record or attachment

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, or null if record does not exist or does not have the attachment

Throws:

BlackboardAccessException - error accessing storages for reading the record or attachment

setAttachment

void setAttachment(java.lang.String id,
                   Attachment attachment)
                   throws BlackboardAccessException

Sets the attachment.

Parameters:

id - the id

attachment - the attachment

Throws:

BlackboardAccessException - error if record does not exist or on errors accessing storages for reading the record or writing the attachment

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 - error if record does not exist or on errors accessing storages for reading the record or writing the attachment

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 - error if record does not exist or on errors accessing storages for reading the record or writing the attachment

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 - error if record does not exist or on errors accessing storages for reading the record or writing the attachment

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 - error if record does not exist or on errors accessing storages for reading the record or deleting the attachment

hasGlobalNote

boolean hasGlobalNote(java.lang.String name)

Checks for global note.

Parameters:

name - the name

Returns:

true, if successful

getGlobalNote

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

Gets the global note.

Parameters:

name - the name

Returns:

the global note

setGlobalNote

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

Sets the global note.

Parameters:

name - the name

object - the object

hasRecordNote

boolean hasRecordNote(java.lang.String id,
                      java.lang.String name)

Checks for record note.

Parameters:

id - the id

name - the name

Returns:

true, if successful

getRecordNote

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

Gets the record note.

Parameters:

id - the id

name - the name

Returns:

the record note

setRecordNote

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

Sets the record note.

Parameters:

id - the id

name - the name

object - the object

commitRecord

void commitRecord(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

unloadRecord

void unloadRecord(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

commit

void commit()
            throws BlackboardAccessException

commit ALL records on this blackboard to storages (if any) and release resources.

The records will not be unloaded from the blackboard.

The operation 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.

unload

void unload()

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