DocumentBus (pepper-framework 3.3.4 API)

java.lang.Object
- org.corpus_tools.pepper.core.DocumentBus

Direct Known Subclasses:

InitialDocumentBus, TerminalDocumentBus
```
public class DocumentBus
extends Object
```
This object is an implementation of a threadsafe queue to store DocumentController objects. Such an object is used to connect multiple ModuleController objects. An DocumentController can only be removed from queue, when all output ModuleController objects requested the DocumentController object.
This object has a list of Ids belonging to ModuleController objects, which are on the output side of this queue. All these objects have to request a document, before this queue can get the status finished. The same goes for ModuleController objects on the input side. All these controllers have to notify this queue to be finished, before the queue can notify the controllers on the output side, that this queue is finished.

Author:

Florian Zipser

Field Summary

Fields
Modifier and Type	Field and Description
`protected Hashtable<String,ConcurrentLinkedQueue<DocumentController>>`	`documentBus` This table is the central management object of the `DocumentBus`.
`protected String`	`id` Id of this object.
`protected List<String>`	`inputModuleControllerIds` A list of Ids belonging to `ModuleController` objects on the input side.
`protected ReentrantLock`	`lock` This lock is used for creating the condition `waitUntilAllDocumentsArePut` to let the `pop(String)` method wait until all documents have been put.
`protected MEMORY_POLICY`	`memPolicy`
`protected List<String>`	`outputModuleControllerIds` A list of Ids belonging to `ModuleController` objects, which are on the output side of this queue.
`protected Condition`	`waitUntilAllDocumentsArePut` Used to let the `pop(String)` method wait until all documents have been put.

Constructor Summary

Constructors
Constructor and Description
`DocumentBus(List<String> inputModuleControllerIds, List<String> outputModuleControllerIds)` Creates an object of this type and sets all passed in- and output `ModuleController` objects.
`DocumentBus(List<String> inputModuleControllerIds, String outputModuleControllerId)` Creates an object of this type and sets the passes the given input controller and output controller.
`DocumentBus(String inputModuleControllerId, List<String> outputModuleControllerIds)` Creates an object of this type and sets the passes the given input controller and output controller.
`DocumentBus(String inputModuleControllerId, String outputModuleControllerId)` Creates an object of this type and sets the passes the given input controller and output controller.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`finish(String inputControllerId)` Sets the entry corresponding to given id to status finished, which means, that when all listed `ModuleController` objects on input side, are set to status finish, this queue is finished and no further documents are passed to `ModuleController` objects on output side.
`Hashtable<String,ConcurrentLinkedQueue<DocumentController>>`	`getDocumentBus()` Returns the table, which is the central management object of the `DocumentBus`.
`String`	`getId()` Creates an id for this object. the id consists of the in- and output `DocumentController` objects.
`List<String>`	`getInputControllerIds()` Returns a list of Ids belonging to `ModuleController` objects on the input side.
`MEMORY_POLICY`	`getMemPolicy()` Returns the set memory policy.
`List<String>`	`getOutputControllerIds()` Returns a list of Ids belonging to `ModuleController` objects, which are on the output side of this queue.
`PepperJobImpl`	`getPepperJob()` Returns the `PepperJob` object containing this object
`protected void`	`init(List<String> inputModuleControllerIds, List<String> outputModuleControllerIds)` Creates an object of this type and passes all output `ModuleController` objects.
`protected void`	`initDocumentBus(List<String> outputModuleControllerIds)` Initializes the table, which is the central management object of the `DocumentBus`.
`boolean`	`isFinished()` Returns true, whether all input `ModuleController` objects called the `finish(String)` method and set this object to status finish.
`DocumentController`	`pop(String outputControllerId)` Returns a `DocumentController` object, which is on first place of the internal queue (regarding the FIFO principle).
`DocumentController`	`pop(String outputControllerId, boolean ignorePermissionForDocument)` Returns a `DocumentController` object, which is on first place of the internal queue (regarding the FIFO principle).
`void`	`put(DocumentController documentController)` Adds the given `DocumentController` object to the queue.
`void`	`setMemPolicy(MEMORY_POLICY memPolicy)` Sets the memory policy.
`void`	`setPepperJob(PepperJobImpl pepperJob)` Sets the `PepperJob` object containing this object
`String`	`toString()` returns a String representation of this object.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - outputModuleControllerIds
```
protected List<String> outputModuleControllerIds
```
    A list of Ids belonging to ModuleController objects, which are on the output side of this queue. All these objects have to request a document, before this queue can get the status finished.
  - inputModuleControllerIds
```
protected List<String> inputModuleControllerIds
```
    A list of Ids belonging to ModuleController objects on the input side. All these controllers have to notify this queue to be finished, before the queue can notify the controllers on the output side, that this queue is finished.
  - id
```
protected String id
```
    Id of this object.
  - documentBus
```
protected volatile Hashtable<String,ConcurrentLinkedQueue<DocumentController>> documentBus
```
    This table is the central management object of the DocumentBus. This table relates a queue containing document controllers to a identifier of a ModuleController object. Key= identifier, value= queue
  - memPolicy
```
protected volatile MEMORY_POLICY memPolicy
```
  - lock
```
protected ReentrantLock lock
```
    This lock is used for creating the condition waitUntilAllDocumentsArePut to let the pop(String) method wait until all documents have been put.
  - waitUntilAllDocumentsArePut
```
protected Condition waitUntilAllDocumentsArePut
```
    Used to let the pop(String) method wait until all documents have been put.
- Constructor Detail
  - DocumentBus
```
public DocumentBus(String inputModuleControllerId,
                   String outputModuleControllerId)
```
    Creates an object of this type and sets the passes the given input controller and output controller.
    
    Parameters:
    
    inputModuleControllerId - identifier of controller, which produces documents for this bus
    
    outputModuleControllerId - identifier of controller, which consumes documents for this bus
  - DocumentBus
```
public DocumentBus(String inputModuleControllerId,
                   List<String> outputModuleControllerIds)
```
    Creates an object of this type and sets the passes the given input controller and output controller.
    
    Parameters:
    
    inputModuleControllerId - identifier of controller, which produces documents for this bus
    
    outputModuleControllerIds - list of identifier of controller, which consumes documents for this bus
  - DocumentBus
```
public DocumentBus(List<String> inputModuleControllerIds,
                   String outputModuleControllerId)
```
    Creates an object of this type and sets the passes the given input controller and output controller.
    
    Parameters:
    
    inputModuleControllerIds - list of identifier of controller, which produces documents for this bus
    
    outputModuleControllerId - identifier of controller, which consumes documents for this bus
  - DocumentBus
```
public DocumentBus(List<String> inputModuleControllerIds,
                   List<String> outputModuleControllerIds)
```
    Creates an object of this type and sets all passed in- and output ModuleController objects. This is important, because an DocumentController can only be removed from queue, when all output ModuleController objects requested the DocumentController object.
    
    Parameters:
    
    inputModuleControllerIds - list of identifier of controller, which produces documents for this bus
    
    outputModuleControllerIds - list of identifier of controller, which consumes documents for this bus
- Method Detail
  - init
```
protected void init(List<String> inputModuleControllerIds,
                    List<String> outputModuleControllerIds)
```
    Creates an object of this type and passes all output ModuleController objects. This is important, because an DocumentController can only be removed from queue, when all output ModuleController objects requested the DocumentController object.
    
    Parameters:
    
    outputs -
  - getOutputControllerIds
```
public List<String> getOutputControllerIds()
```
    Returns a list of Ids belonging to ModuleController objects, which are on the output side of this queue. All these objects have to request a document, before this queue can get the status finished.
    
    Returns:
    
    list of all ids
  - getInputControllerIds
```
public List<String> getInputControllerIds()
```
    Returns a list of Ids belonging to ModuleController objects on the input side. All these controllers have to notify this queue to be finished, before the queue can notify the controllers on the output side, that this queue is finished.
    
    Returns:
    
    list of all ids
  - getId
```
public String getId()
```
    Creates an id for this object. the id consists of the in- and output DocumentController objects.
    
    Returns:
  - getPepperJob
```
public PepperJobImpl getPepperJob()
```
    Returns the PepperJob object containing this object
    
    Returns:
    
    PepperJob object containing this
  - setPepperJob
```
public void setPepperJob(PepperJobImpl pepperJob)
```
    Sets the PepperJob object containing this object
    
    Parameters:
    
    pepperJob - PepperJob object containing this
  - getDocumentBus
```
public Hashtable<String,ConcurrentLinkedQueue<DocumentController>> getDocumentBus()
```
    Returns the table, which is the central management object of the DocumentBus. This table relates a queue containing document controllers to a identifier of a ModuleController object. Key= identifier, value= queue
    
    Returns:
  - initDocumentBus
```
protected void initDocumentBus(List<String> outputModuleControllerIds)
```
    Initializes the table, which is the central management object of the DocumentBus. This table relates a queue containing document controllers to a identifier of a ModuleController object. Key= identifier, value= queue.
    Please take care not to call this method, when this object is already started, since this will confuse the started process.
    
    Parameters:
    
    outputModuleControllerIds - a list of ids of the ModuleController objects on the output side.
  - getMemPolicy
```
public MEMORY_POLICY getMemPolicy()
```
    Returns the set memory policy.
    
    Returns:
  - setMemPolicy
```
public void setMemPolicy(MEMORY_POLICY memPolicy)
```
    Sets the memory policy. Don't change the memory policy, when job was started.
    
    Parameters:
    
    memPolicy -
  - finish
```
public void finish(String inputControllerId)
```
    Sets the entry corresponding to given id to status finished, which means, that when all listed ModuleController objects on input side, are set to status finish, this queue is finished and no further documents are passed to ModuleController objects on output side.
    
    Parameters:
    
    inputControllerId - id of controller to be set to finish.
  - isFinished
```
public boolean isFinished()
```
    Returns true, whether all input ModuleController objects called the finish(String) method and set this object to status finish.
    
    Returns:
    
    if all input controllers called finished
  - put
```
public void put(DocumentController documentController)
```
    Adds the given DocumentController object to the queue.
    
    Parameters:
    
    documentController - the DocumentController object to be added to the queue.
  - pop
```
public DocumentController pop(String outputControllerId)
```
    Returns a DocumentController object, which is on first place of the internal queue (regarding the FIFO principle). When all registered ModuleController objects popped the DocumentController object, it will be removed from internal queue.
    If the document, which is the one to be taken in queue is in sleep mode, it will be woken up, if the PepperJobImpl gives the permission. Otherwise, this method waits for the permission.
    Caution, call this method can take some time, since it waits for two conditions:
    1. a document is waiting in the queue, and the preceding PepperModule has not finished all documents
    2. the Pepper framework (more precisely the PepperJobImpl) gives the permission to wake up the document, if it was in sleep mode
    Parameters:
    
    moduleController - object requesting the DocumentController object
    
    Returns:
    
    head of the queue.
  - pop
```
public DocumentController pop(String outputControllerId,
                              boolean ignorePermissionForDocument)
```
    Returns a DocumentController object, which is on first place of the internal queue (regarding the FIFO principle). When all registered ModuleController objects popped the DocumentController object, it will be removed from internal queue.
    If the document, which is the one to be taken in queue is in sleep mode, it will be woken up, if the PepperJobImpl gives the permission. Otherwise, this method waits for the permission.
    Caution, call this method can take some time, since it waits for two conditions:
    1. a document is waiting in the queue, and the preceding PepperModule has not finished all documents
    2. the Pepper framework (more precisely the PepperJobImpl) gives the permission to wake up the document, if it was in sleep mode
    In contrast to pop(String), if ignorePermissionForDocument is set to true this method returns a DocumentController object even if the PepperJob permission does not allow to process a further document. This mechanism can be used, if a PepperModule has an own control mechanism of sending SDocuments to sleep.
    Parameters:
    
    outputControllerId - object requesting the DocumentController object
    
    ignorePermissionForDocument - if set, a document will be returned even if the Pepper job gives no permission
    
    Returns:
    
    head of the queue.
  - toString
```
public String toString()
```
    returns a String representation of this object. Note, that this String cannot be used for serialization/deserialization purposes.
    
    Overrides:
    
    toString in class Object

Class DocumentBus

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

outputModuleControllerIds

inputModuleControllerIds

id

documentBus

memPolicy

lock

waitUntilAllDocumentsArePut

Constructor Detail

DocumentBus

DocumentBus

DocumentBus

DocumentBus

Method Detail

init

getOutputControllerIds

getInputControllerIds

getId

getPepperJob

setPepperJob

getDocumentBus

initDocumentBus

getMemPolicy

setMemPolicy

finish

isFinished

put

pop

pop

toString