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 theProgID
property of theCmCustomStorageDevice
defining the device configuration. The handler implementation can be checked in as aCodeModule
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
operation.createContent
static class
StorageDeviceHandler.ContentValidationResult
Object reporting the outcome of a
operation.validateContent
static class
StorageDeviceHandler.ValidationStatus
The result status of a content validation operation.
-
Method Summary
All Methods Instance Methods Abstract Methods 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
instance defining the configuration of the device.CmStorageDevice
-
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
enumeration specifying the capability being queried.Capability
- 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 theaccessRequired
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
and cannot test any objects created by that method.initializeStorage
- 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
) support for synchronous replication (seecapabilitySupported
) it must store the content such that it can be retrieved or deleted using only theSYNCHRONOUS_REPLICATION
contentId
andhashSequence
values passed to this method, and must returnnull
for thedeviceIdentity
parameter of the
returned. Only if the handler does not support synchronous replication may a non-nullContentCreationResult
deviceIdentity
be returned.If the
asynchReplication
parameter istrue
the handler must check if the content already exists on the device, and if so return without reading from the source stream, reportingtrue
for theexisted
parameter of of the
returned and giving the size of the existing content through theContentCreationResult
size
parameter of same.If
asynchReplication
isfalse
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
instance providing a unique identity for the content item.Id
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
instance giving the results of the creation operation (if successful).ContentCreationResult
-
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
rather than one that extends simplyExtendedInputStream
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
method call that created it in the device.createContent
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
method).createContent
deviceIdentity
- If the device is not capable of synchronous replication (see
) the device-generated unique identifier for the content item as returned bySYNCHRONOUS_REPLICATION
.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
method call that created it in the device.createContent
hashSequence
- The sequence number likewise.deleteMethod
- A member of the
class specifying the secure delete method to be applied. The method specified will not exceed the sophistication of the device as expressed by theAreaDeleteMethod
) capability.DELETE METHOD
deviceIdentity
- If the device is not capable of synchronous replication (see
) the device-generated unique identifier for the content item as returned bySYNCHRONOUS_REPLICATION
.createContent
- Returns:
true
if the content existed on the device and has been successfully deleted, orfalse
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
method call that created it in the device.createContent
hashSequence
- The sequence number likewise.deleteMethod
- A member of the
class specifying the secure delete method to be applied. The method specified will not exceed the sophistication of the device as expressed by theAreaDeleteMethod
) capability.DELETE METHOD
- Returns:
true
if the content existed on the device and has been successfully deleted, orfalse
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
method call that created it in the device.createContent
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 replicationdeviceIdentity
- If the device is not capable of synchronous replication (see
) the device-generated unique identifier for the content item as returned bySYNCHRONOUS_REPLICATION
.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
giving the results of the validation operation.ContentValidationResult
-
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.
-
-