SMILA (incubation) API documentation

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.
 byte[] getAttachment(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.
 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 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, 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

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

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

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, 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,
                   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.


SMILA (incubation) API documentation