Package com.priint.pubserver.plugin.interfaces

Interface PluginControl

All Known Subinterfaces:
AuthenticationLocal, AuthenticationRemote, CometServer4JobRemote, ConnectorLocal, ConnectorPersistLocal, ConnectorPersistRemote, ConnectorRemote, DataProviderManagerLocal, DataProviderManagerRemote, EntityManagerLocal, EntityManagerRemote, ErrorCodeManagerLocal, ErrorCodeManagerRemote, MediaAssetProcessingLocal, MediaAssetProcessingRemote, ParameterQueryLocal, ParameterQueryRemote, PersistConnectorLocal, PersistConnectorRemote, PublishingManagementConnector, PubServerDeploymentManagerLocal, PubServerDeploymentManagerRemote
All Known Implementing Classes:
AbstractConnector, CometPublicationPluginDefault, PluginControlDefault, ProductDataMappingDefault, PublicationUtils, SearchAfterBucketsAbstractPlugin
public interface PluginControl

Basic interface that all plug-ins must implement.

Usually you don't implement this interface directly, but inherit from the default implementation PluginControlDefault instead.
This class provides default implementations for all interface methods, so the following code fragment is all that is required to implement a fully working PubServer plugin: 

 @Stateless(mappedName=MyPlugin.MAPPED_NAME)
 // or:
 @Singleton(mappedName=MyPlugin.MAPPED_NAME)
 @PubServerPlugin
 public class MyPlugin extends PluginControlDefault {
     public static final String MAPPED_NAME = "com.customer.domain.MyPlugin";
 }

  • Method Details

    • initInstance

      void initInstance(String mappedName, String instanceName) throws PluginException
      Will be called when a plug-in is created by the plugin manager.

      Typically used with stateful beans, e.g. connectors, that provide named instances.

      Do not use with stateless beans. For stateless beans use @PostConstruct instead.

      Parameters:
      mappedName - Mapped name as defined in the @Stateful bean annotation of the plugin class.
      instanceName - Name of the specific instance of the plug-in, if multiple instances are allowed. e.g. if you have variant of a connector running alternatively with database schema 1 and schema 2 of a content system, or a viewer plug-in supporting legacy web-browsers and mobile browser, etc.
      Throws:
      PluginException

    • loadServerConfig

      void loadServerConfig() throws PluginException
      Called by plug-in manager or other modules if they intend a (re)load of configuration files to be done by the plug-in. Implementation details are up to the plug-in.
      Throws:
      PluginException

    • updateConfigurations

      PluginConfigCollection updateConfigurations(String sessionId, PluginConfigCollection updateConfigs) throws PluginException

      Called by the ConfigManager before configurations in the domain of this plugin are created or updated.

      This method allows plugin developers to react to configuration changes. If the plugin is derived from PluginControlDefault, there is usually no need to override the default implementation.
      You can override this method, to

      • change the application status (e.g. clean caches etc.), depending on the items being updated
      • pre-process files (e.g. calculate fields or dependencies) of items being updated
      • add configuration files to the set of files, which are to be updated or created
      • remove files from the set of files, which are to be updated or created

      This method is called at the beginning of the update processing chain, i.e. before calculating dependencies and before persisting items in the repository. Items contained in the updateConfig collection do not necessarily exist in the repository at this stage. By removing items from the collection, you can prevent certain files from being updated or created at all.

      If the method returns null, the return value is ignored and the collection passed to the method as parameter is used for further processing.

      Note: this method is called outside of the checkin transaction. If you perform checkin or delete operations in your updateConfigurations implementation, these are run as separate transactions. If the main transaction fails, these transactions will not be rolled back.

      Note: starting with Version 4.1 / Revision 12465, there are two important changes to the behavior of this method:

      1. this method may be called several times during an update process:
        • the first call contains the list of files requested for update, which was provided by the client
        • the second call contains additional dependent files found for the list of files returned by the first call
        • subsequent calls contain additional dependent files found for the list of files obtained from the previous call
      2. this method may be called during a delete process, if deletion of certain configurations triggers changes in dependent files. The method is not called for files, which are to be deleted anyway.
      One more important note: notification for each file is send only once during one transaction or transaction branch, so PluginControl implementations do not need to bother about circular dependencies / nested transactions, which trigger the same dependencies etc.

      The default implementation is: 

       public PluginConfigCollection updateConfigurations(
           String sessionId,
           PluginConfigCollection updateConfigs) throws PluginException {
        return updateConfigs;
 }

      This would have the same effect: 

       public PluginConfigCollection updateConfigurations(
           String sessionId,
           PluginConfigCollection updateConfigs) throws PluginException {
        return null;
 }

      To process and return all configurations, use this code skeleton: 

       public PluginConfigCollection updateConfigurations(
           String sessionId
           PluginConfigCollection updateConfigs) throws PluginException {
        for (String path : updateConfigs.getKeySet()) {
            PluginConfigDataHandler config = updateConfigs.getConfigDataHandler(path);
            //
            // TODO: your pre-processing...
            //
         }
         return updatedConfigs; // returning null would have the same effect
 }

      Disallow any configuration changes: 

       public PluginConfigCollection updateConfigurations(
           String sessionId,
           PluginConfigCollection updateConfigs) throws PluginException {
         return PluginConfigCollection.createEmptySet();
 }

      Parameters:
      sessionId - Identifier of the current session
      updateConfigs - the configurations currently being updated
      Returns:
      the pre-processed or filtered configuration items or null, if the updateConfigs collection should be used for further processing.
      Throws:
      PluginException

    • deleteConfigurations

      PluginConfigCollection deleteConfigurations(String sessionId, PluginConfigCollection deleteConfigs) throws PluginException

      Called by the ConfigManager before configurations in the domain of this plugin are deleted.

      This method allows plugin developers to react to configuration deletion. If the plugin is derived from PluginControlDefault, there is usually no need to override the default implementation.
      You can override this method, to

      • change the application status (e.g. clean caches etc.), depending on the items being deleted
      • pre-process files (e.g. calculate fields or dependencies) of items being deleted
      • add configuration files to the set of files, which are to be deleted
      • remove files from the set of files, which are to be deleted

      This method is called at the beginning of the delete processing chain, i.e. before calculating dependencies and before moving items to trash. By removing certain items from the collection, you can prevent certain files from being deleted at all.

      If the method returns null, the return value is ignored and the collection passed to the method as parameter is used for further processing.

      Note: this method is called outside of the delete transaction. If you perform checkin or delete operations in your deleteConfigurations implementation, these are run as separate transactions. If the main transaction fails, these transactions will not be rolled back.

      The default implementation is: 

       public PluginConfigCollection deleteConfigurations(
           String sessionId,
           PluginConfigCollection deleteConfigs) throws PluginException {
         return deleteConfigs;
 }

      This would have the same effect: 

       public PluginConfigCollection deleteConfigurations(
           String sessionId,
           PluginConfigCollection deleteConfigs) throws PluginException {
         return null;
 }

      To process and return all configurations, use this code skeleton: 

       public PluginConfigCollection deleteConfigurations(
           String sessionId
           PluginConfigCollection deleteConfigs) throws PluginException {
         for (String path : updateConfigs.getKeySet()) {
             PluginConfigDataHandler config = deleteConfigs.getConfigDataHandler(path);
             //
             // TODO: your pre-processing...
             //
         }
         return deleteConfigs; // returning null would have the same effect
 }

      Disallow any deletion: 

       public PluginConfigCollection deleteConfigurations(
           String sessionId,
           PluginConfigCollection deleteConfigs) throws PluginException {
         return PluginConfigCollection.createEmptySet();
 }

      Parameters:
      sessionId - Identifier of the current session
      deleteConfigs - the configurations currently being deleted
      Returns:
      the pre-processed or filtered configuration items or null, if the deleteConfigs collection should be used for further processing.
      Throws:
      PluginException

    • createConfiguration

      String createConfiguration(String sessionId, String customTypeName, Map<String,Object> initialValues) throws PluginException

      Create a new config file of type customTypeName.

      The method must

      • create a PluginConfig object with a embedded customClazz element
      • check in the initial revision of this configuration
      • return the full repository path of the new configuration
      • throw an exception, if it's not possible to create a new configuration (e.g. illegal type name, invalid initialValues etc.)

      It's up to the implementation to

      • resolve the custom type name. This can be a qualified class name or XML type name
      • evaluate initialValues. There are no Kernel requirements for the initialValues Map, you can specify arbitrary key names and value semantics suitable for your requirements.

      Example: 

       public String createConfiguration(
           String sessionId,
           String customTypeName,
           Map<String,Object> initialValues) throws PluginException {
         if (customTypeName != null && customTypeName.equals("MyConfigClass")) {
             String path                = "calculated path";

             // instantiate and initialize cutom configuration object
             final String objectName = (initialValues.containsKey("name") ? initialValues.get("name") + "" : "untitled");
             Object customObject     = new Object() { public final String toString() { return objectName; } };

             // instantiate configuration wrapper
             PluginConfig config = new PluginConfig();
             config.setCustomConfig(customObject);
             config.setDescription("Object with name " + objectName);
             config.setName(objectName);
             config.setType("MyConfigClass");

             // add to new PluginConfig collection:
             PluginConfigCollection collection = PluginConfigCollection.createEmptySet(null);
             collection.addConfig(path, config);

             // lookup ConfigManager and call checkin
             ConfigManagerLocal configManager; // lookup etc.
             configManager.checkinListOfConfigFiles(sessionId, collection, false);

             // check, if the new configuration file really does exist in repository
             if (configManager.exists(path)) {
                 return path;
             }
             throw new PluginException (this, -1, "File does not exist in repository");
         }
         else {
             throw new InvalidArgumentException(
                         this,
                         "Custom type name '" + customTypeName + "' cannot be created in Plugin '" + this.getClass().getName() + "'");
         }
 }

      Parameters:
      sessionId - Identifier of the current session
      customTypeName -
      initialValues -
      Returns:
      full repository path of the new configuration.
      Throws:
      PluginException

    • afterUpdateConfigurations

      void afterUpdateConfigurations(String sessionId, PluginConfigCollection updatedConfigs) throws PluginException

      This method is called by the ConfigurationManager after the check-in of configuration files.

      Usually the implementation of this method will trigger the reload of the configuration.
      If your application caches configurations, this would be the right place to refresh caches.

      Note: starting with Version 4.1, Revision 12465, the list of files also contains all dependent files, which were updated.
      Furthermore, this method is also called after updating dependent files during a delete process.

      Parameters:
      sessionId - Identifier of the current session
      updatedConfigs - collection of configurations that have being updated
      Throws:
      PluginException

    • afterDeleteConfigurations

      void afterDeleteConfigurations(String sessionId, PluginConfigCollection deletedConfigs) throws PluginException

      This method is called by the ConfigurationManager after deleting configuration files.

      Usually the implementation of this method will trigger the reload of the configuration. If your application caches configurations, this would be the right place to refresh caches.

      Note: starting with Version 4.1, Revision 12465, the list of files also contains all dependent files, which were deleted.

      Parameters:
      sessionId - Identifier of the current session
      deletedConfigs - the configurations that have being deleted
      Throws:
      PluginException

    • afterCreateConfigurations

      void afterCreateConfigurations(String sessionId, PluginConfigCollection createdConfigs) throws PluginException

      This method is called by the ConfigurationManager after adding configuration files.

      Usually the implementation of this method will trigger the reload of the configuration.

      Parameters:
      sessionId - Identifier of the current session
      createdConfigs - the configurations that have being created
      Throws:
      PluginException

    • ping

      @Deprecated String ping()
      Deprecated.

    • validateConfigurations

      default void validateConfigurations(PluginConfigCollection configCollection) throws PluginException
      Validate a list of plug-in configurations.

      This will throw an exception if a configuration is null.
      If will also throw an exception if the configuration is not XML schema valid.
      It might also throw an exception if other more specific requirements of the plug-in are not met.

      Please refer to the detailed message of the exception for more information.

      The default implementation of this methods will just pass through.

      Parameters:
      configCollection -
      Throws:
      PluginException - if any configuration is null or invalid.
      Since:
      4.1.6