ResourceProcessor
Date: 2016-06-25

org.osgi.service.deploymentadmin.spi

## Interface ResourceProcessor

-     public interface ResourceProcessor

  ResourceProcessor interface is implemented by processors handling resource files in deployment packages. Resource Processors expose their services as standard OSGi services. Bundles exporting the service may arrive in the deployment package (customizers) or may be preregistered (they are installed previously). Resource processors has to define the `service.pid` standard OSGi service property which should be a unique string.

  The order of the method calls on a particular Resource Processor in case of install/update session is the following:

  1. `begin(DeploymentSession)`
  2. `process(String, InputStream)` calls till there are resources to process or `rollback()` and the further steps are ignored
  3. `dropped(String)` calls till there are resources to drop
  4. `prepare()`
  5. `commit()` or `rollback()`
  The order of the method calls on a particular Resource Processor in case of uninstall session is the following:

  1. `begin(DeploymentSession)`
  2. `dropAllResources()` or `rollback()` and the further steps are ignored
  3. `prepare()`
  4. `commit()` or `rollback()`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `begin(DeploymentSession session)` Called when the Deployment Admin starts a new operation on the given deployment package, and the resource processor is associated a resource within the package.
    `void` | `cancel()` Processing of a resource passed to the resource processor may take long.
    `void` | `commit()` Called when the processing of the current deployment package is finished.
    `void` | `dropAllResources()` This method is called during an "uninstall" deployment session.
    `void` | `dropped(java.lang.String resource)` Called when a resource, associated with a particular resource processor, had belonged to an earlier version of a deployment package but is not present in the current version of the deployment package.
    `void` | `prepare()` This method is called on the Resource Processor immediately before calling the `commit` method.
    `void` | `process(java.lang.String name, java.io.InputStream stream)` Called when a resource is encountered in the deployment package for which this resource processor has been selected to handle the processing of that resource.
    `void` | `rollback()` Called when the processing of the current deployment package is finished.

- - ### Method Detail

    - #### begin

          void begin(DeploymentSession session)

      Called when the Deployment Admin starts a new operation on the given deployment package, and the resource processor is associated a resource within the package. Only one deployment package can be processed at a time.
      Parameters:
        `session` - object that represents the current session to the resource processor
      See Also:
        `DeploymentSession`

    - #### process

          void process(java.lang.String name,
                     java.io.InputStream stream)
                       throws ResourceProcessorException

      Called when a resource is encountered in the deployment package for which this resource processor has been selected to handle the processing of that resource.
      Parameters:
        `name` - The name of the resource relative to the deployment package root directory.
        `stream` - The stream for the resource.
      Throws:
        `ResourceProcessorException` - if the resource cannot be processed. Only `ResourceProcessorException.CODE_RESOURCE_SHARING_VIOLATION` and `ResourceProcessorException.CODE_OTHER_ERROR` error codes are allowed.

    - #### dropped

          void dropped(java.lang.String resource)
                       throws ResourceProcessorException

      Called when a resource, associated with a particular resource processor, had belonged to an earlier version of a deployment package but is not present in the current version of the deployment package. This provides an opportunity for the processor to cleanup any memory and persistent data being maintained for the particular resource. This method will only be called during "update" deployment sessions.
      Parameters:
        `resource` - the name of the resource to drop (it is the same as the value of the "Name" attribute in the deployment package's manifest)
      Throws:
        `ResourceProcessorException` - if the resource is not allowed to be dropped. Only the `ResourceProcessorException.CODE_OTHER_ERROR` error code is allowed

    - #### dropAllResources

          void dropAllResources()
                                throws ResourceProcessorException

      This method is called during an "uninstall" deployment session. This method will be called on all resource processors that are associated with resources in the deployment package being uninstalled. This provides an opportunity for the processor to cleanup any memory and persistent data being maintained for the deployment package.
      Throws:
        `ResourceProcessorException` - if all resources could not be dropped. Only the `ResourceProcessorException.CODE_OTHER_ERROR` is allowed.

    - #### prepare

          void prepare()
                       throws ResourceProcessorException

      This method is called on the Resource Processor immediately before calling the `commit` method. The Resource Processor has to check whether it is able to commit the operations since the last `begin` method call. If it determines that it is not able to commit the changes, it has to raise a `ResourceProcessorException` with the `ResourceProcessorException.CODE_PREPARE` error code.
      Throws:
        `ResourceProcessorException` - if the resource processor is able to determine it is not able to commit. Only the `ResourceProcessorException.CODE_PREPARE` error code is allowed.

    - #### commit

          void commit()

      Called when the processing of the current deployment package is finished. This method is called if the processing of the current deployment package was successful, and the changes must be made permanent.

    - #### rollback

          void rollback()

      Called when the processing of the current deployment package is finished. This method is called if the processing of the current deployment package was unsuccessful, and the changes made during the processing of the deployment package should be removed.

    - #### cancel

          void cancel()

      Processing of a resource passed to the resource processor may take long. The `cancel()` method notifies the resource processor that it should interrupt the processing of the current resource. This method is called by the `DeploymentAdmin` implementation after the `DeploymentAdmin.cancel()` method is called.