com.filenet.api.engine

Interface StorageDeviceHandler

public interface StorageDeviceHandler

The interface that must be implemented by the handler for a content storage device. The name of the class that implements the handler for a custom storage device is specified through the ProgID property of the CmCustomStorageDevice defining the device configuration. The handler implementation can be checked in as a CodeModule object, or can be placed in the classpath of the application server where the Content Engine is running. A handler implementation must be concurrency-safe, meaning that it must be capable of handling multiple overlapping method calls in different threads. Ideally it should accomplish that without synchronization/blocking.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	StorageDeviceHandler.Capability The variable capabilities of the storage device.
static class	StorageDeviceHandler.ContentCreationResult Object reporting the details of a successful createContent operation.
static class	StorageDeviceHandler.ContentValidationResult Object reporting the outcome of a validateContent operation.
static class	StorageDeviceHandler.ValidationStatus The result status of a content validation operation.

Method Summary

Modifier and Type	Method and Description
boolean	backoutContent(Id contentId, long hashSequence, AreaDeleteMethod deleteMethod) Deletes an abandoned content item from the device.
int	capabilitySupported(StorageDeviceHandler.Capability capability) Return this handler's level of support for a given capability.
StorageDeviceHandler.ContentCreationResult	createContent(java.io.InputStream source, Id contentId, long hashSequence, boolean asyncReplication) Create the content item for a single content element from an InputStream.
boolean	deleteContent(Id contentId, long hashSequence, AreaDeleteMethod deleteMethod, java.lang.String deviceIdentity) Delete a content item from the device.
void	disconnect() Called when the server is about to cease operations through the handler instance.
void	initializeStorage(int phase) Initialize a newly configured device, performing any operations required in order to prepare the device for storing content.
void	load(CmStorageDevice configuration) Load and initialize the handler instance without attempting to access the media of the device.
java.io.InputStream	openContent(Id contentId, long hashSequence, long storedSize, java.lang.String deviceIdentity) Open an existing content item for retrieval, returning an input stream.
boolean	testConnectivity(boolean accessRequired) Test connectivity to the device.
StorageDeviceHandler.ContentValidationResult	validateContent(Id contentId, long hashSequence, long size, boolean autoRepairWithinReplica, java.lang.String deviceIdentity, boolean logWarningForMissingContent) Validate the existence and size of a content item, and, at the discretion of the handler, perform other checks to confirm that the content has not been tampered with.

Method Detail

load

void load(CmStorageDevice configuration)

Load and initialize the handler instance without attempting to access the media of the device. This method is called before any other method on the handler instance. In general, this method should only do the "static" initialization, such as loading configuration parameters, any task that relies on a valid connection to the storage device should not be done here. In another word, we don't expect this method to throw exception if the device configuration is valid.

Parameters:

configuration - The CmStorageDevice instance defining the configuration of the device.

capabilitySupported

int capabilitySupported(StorageDeviceHandler.Capability capability)

Return this handler's level of support for a given capability. Note that it is assumed that these are intrinsic capabilities of the handler that do not vary according to the configuration of a device instance.

Parameters:

capability - One of the members of the Capability enumeration specifying the capability being queried.

Returns:

The integer answer regarding the queried capability. Refer to the Capability members descriptions for details of what values should be returned in each case. If the handler does not recognise the capability in question it should return -1.

testConnectivity

boolean testConnectivity(boolean accessRequired)

Test connectivity to the device. The intent is to support both a fast and a slow validation, depending on the value of the accessRequired parameter. The fast validation is used during normal operation when determining if a CPE server has access to a replica (quick, simple validation is allowed). The slow validation is used when the device configuration is being updated and must fully confirm the validity of the configured properties before the changes are committed.

Note that the handler must not assume that the storage device has been initialized by a prior call to initializeStorage and cannot test any objects created by that method.

Parameters:

accessRequired - If true, invokes the slow validation. In this case the method will throw an exception if the device cannot be accessed (with information about it cannot be accessed in the exception data). If false, the fast validation is applied and the method does not throw an exception. Instead it returns false if the device cannot be accessed.

Returns:

true if an only if the device is accessible.

initializeStorage

void initializeStorage(int phase)

Initialize a newly configured device, performing any operations required in order to prepare the device for storing content. For example, a file system device may require that a set of directories be created before content can be stored.

A device is initialized in two phases. In phase one, the handler validates that it has access to the device, and may perform preliminary fast initialization operations (phase one is subject to a database transaction timeout). In phase two, the handler performs the remaining initialization as needed (phase two is not subject to a database transaction timeout).

Parameters:

phase - The initialization phase being invoked, either 1 or 2.

createContent

StorageDeviceHandler.ContentCreationResult createContent(java.io.InputStream source,
                                                         Id contentId,
                                                         long hashSequence,
                                                         boolean asyncReplication)

Create the content item for a single content element from an InputStream. The handler writes the content to the device as is (a byte for byte copy of the data read from the stream).

If the handler has claimed (through capabilitySupported) support for synchronous replication (see SYNCHRONOUS_REPLICATION) it must store the content such that it can be retrieved or deleted using only the contentId and hashSequence values passed to this method, and must return null for the deviceIdentity parameter of the ContentCreationResult returned. Only if the handler does not support synchronous replication may a non-null deviceIdentity be returned.

If the asynchReplication parameter is true the handler must check if the content already exists on the device, and if so return without reading from the source stream, reporting true for the existed parameter of of the ContentCreationResult returned and giving the size of the existing content through the size parameter of same.

If asynchReplication is false the handler is not required to check for pre-existing content, and may simply overwrite what exists already. However, it is permitted to check if that can be done without performance cost and in this case the handler should throw an exception if the content is found to already exist.

Parameters:

source - The InputStream providing the content to be stored.

contentId - Server-generated Id instance providing a unique identity for the content item.

hashSequence - A non-unique long value that can be used by the handler to determine the location of a content item. The value is useful when the device requires distribution of content items, for example distribution of files in a directory structure, or distribution of cloud content across multiple buckets.

asyncReplication - true if the content is being created by an asynchronous replication operation, false otherwise.

Returns:

A ContentCreationResult instance giving the results of the creation operation (if successful).

openContent

java.io.InputStream openContent(Id contentId,
                                long hashSequence,
                                long storedSize,
                                java.lang.String deviceIdentity)

Open an existing content item for retrieval, returning an input stream. The stream that is returned must always be positioned at the first byte of the content; if the CPE needs to advance the stream before reading content, it will use the skip method of the input stream.

If the device is capable of retrieving from arbitrary positions within the content it should return a stream that extends ExtendedInputStream rather than one that extends simply InputStream.

The handler is responsible for ensuring that the stream returned remains functional up until the point that it is closed, even if the handler instance that returned it is disconnected before that time.

Parameters:

contentId - The unique identifier of the content item, as provided to the createContent method call that created it in the device.

hashSequence - The sequence number likewise.

storedSize - The expected size of the content, as stored on the device (i.e. the number of bytes returned from the createContent method).

deviceIdentity - If the device is not capable of synchronous replication (see SYNCHRONOUS_REPLICATION) the device-generated unique identifier for the content item as returned by createContent.

deleteContent

boolean deleteContent(Id contentId,
                      long hashSequence,
                      AreaDeleteMethod deleteMethod,
                      java.lang.String deviceIdentity)

Delete a content item from the device.

Parameters:

contentId - The unique identifier of the content item, as provided to the createContent method call that created it in the device.

hashSequence - The sequence number likewise.

deleteMethod - A member of the AreaDeleteMethod class specifying the secure delete method to be applied. The method specified will not exceed the sophistication of the device as expressed by the DELETE METHOD) capability.

deviceIdentity - If the device is not capable of synchronous replication (see SYNCHRONOUS_REPLICATION) the device-generated unique identifier for the content item as returned by createContent.

Returns:

true if the content existed on the device and has been successfully deleted, or false if the content no longer exists. An exception should be thrown if the content cannot be deleted or if it cannot be proved that it no longer exists.

backoutContent

boolean backoutContent(Id contentId,
                       long hashSequence,
                       AreaDeleteMethod deleteMethod)

Deletes an abandoned content item from the device. Abandoned content is that which was uploaded synchronously but for which a commit was never received for the content-containing object.

This method will only be called for a device capable of synchronous replication.

Parameters:

contentId - The unique identifier of the content item, as provided to the createContent method call that created it in the device.

hashSequence - The sequence number likewise.

deleteMethod - A member of the AreaDeleteMethod class specifying the secure delete method to be applied. The method specified will not exceed the sophistication of the device as expressed by the DELETE METHOD) capability.

Returns:

true if the content existed on the device and has been successfully deleted, or false if the content no longer exists. An exception should be thrown if the content cannot be deleted or if it cannot be proved that it no longer exists.

validateContent

StorageDeviceHandler.ContentValidationResult validateContent(Id contentId,
                                                             long hashSequence,
                                                             long size,
                                                             boolean autoRepairWithinReplica,
                                                             java.lang.String deviceIdentity,
                                                             boolean logWarningForMissingContent)

Validate the existence and size of a content item, and, at the discretion of the handler, perform other checks to confirm that the content has not been tampered with.

Parameters:

contentId - The unique identifier of the content item, as provided to the createContent method call that created it in the device.

hashSequence - The sequence number likewise.

autoRepairWithinReplica - Boolean value to indicate whether doing autoRepairContent if content is missing depending on storage device support. The autoRepair is a repair within a replica not going through replication

deviceIdentity - If the device is not capable of synchronous replication (see SYNCHRONOUS_REPLICATION) the device-generated unique identifier for the content item as returned by createContent.

logWarningForMissingContent - If it is set to true, no warning or errors will be logged in the content missing case. This is used for ASA content replication to adjust for previous replication. The value should be set to false for a normal content validation use case.

Returns:

An instance of ContentValidationResult giving the results of the validation operation.

disconnect

void disconnect()

Called when the server is about to cease operations through the handler instance. The handler should perform whatever processing is necessary to disconnect from the device and free up resources related to it.

Note that the disconnect method is only called once for a handler instance, and only after all in-progress method calls to it have completed. However calls to content streams opened by the handler may be made after it is disconnected.