Difference between revisions of "SMILA/Documentation/Usage of Blackboard Service"

Revision as of 08:41, 23 January 2012

What is the blackboard?

The blackboard holds the records while they are pushed through a pipeline. Pipelets are invoked with a blackboard instance and a list of IDs of records to process. The pipelet can then access the blackboard to get record metadata and attachments. The blackboard The blackboard hides the handling of record persistence from the services. For example it can be configured to hold only the record metadata in memory, but to put the attachments in the BinaryStorage service to save memory, if large attachments are used or many records are processed at the same time. Or it could get a record from a RecordStorage service on demand and write it back if processing is done (however, in SMILA 1.0 we do not use the RecordStorage by default anymore).

For pipelet programmers, using the blackboard is usually trivial:

• Use getRecord(id) or getMetadata(id) to get the record metadata. Modify the returned object to change record metadata.
• To access record attachments, you should use the get/setAttachment methods of the blackboard. The Attachment objects of the Record object returned by getRecord(id) may not allow access to the attachment content, if the content has been swapped out to BinaryStorage.

Creation and lifecycle of blackboard

Service interfaces

see Repository:

• BlackboardFactory.java
• Blackboard.java

Usage of blackboard

Discussion
happens @ bug 336818

Record access

• Record getRecord(String id);

  Gets the record with its complete metadata. You should not rely on the record having all attachment values attached, only the names will be available. Use the blackboard attachments access methods to access attachments. If the record is not yet loaded in the blackboard, the PersistingBlackboard will return null, if it has a RecordStorage set and the record does not exist in record storage. If it doesn't have a RecordStorage a new record is created automatically. The TransientBlackboard creates a new record, too, if necessary. If you change the record metadata, you change the record stored on the blackboard, too, so you don't have to call setRecord() to write back the changes explicitly.

• AnyMap getMetadata(String id);

  A shortcut for getRecord(id).getMetadata()

• Record getRecord(String id, String filterName);

  Creates a copy of the record with only those metadata elements allowed by the named record filter. Changes done to the filtered metadata are not applied to the original record automatically.

• Record filterRecord(Record record, String filterName);

  Applies a record filter known to the blackboard to a record which does not have to be loaded on the blackboard.

Attachments management

There are following methods for working with Record attachments in the blackboard:

• setAttachment(id, name, byte[]);
• setAttachmentFromStream(id, name, InputStream);
• byte[] getAttachment(id, name);
• InputStream getAttachmentAsStream(id, name);
• boolean hasAttachment(id, name);

Attachments are not stored anywhere in the blackboard, they are saved to BinStorage directly and the actual attachment value in the corresponding record is replaced by null. It is highly recommended to use only Stream methods to manage attachments because loading the whole attachments in memory will cause great memory consumption and may cause application crashes.

Usage of blackboard notes

Notes are additional temporary data created by pipelets to be used in later pipelets in the same workflow, but not to be persisted in the storages. Notes can be either global or record specific (associated with a record ID). Record specific notes are copied on record splits and removed when the associated record is removed from the blackboard. Each Note has a String name and Serialaizable value. There are following methods for working with Notes:

• boolean hasGlobalNote(name);
• Serializable getGlobalNote(name);
• setGlobalNote(name, value);
• boolean hasRecordNote(id, name);
• getRecordNote(id, name);
• setRecordNote(id, name, value);