Package com.priint.pubserver.plugin.interfaces

Interface PluginControl

    • Method Detail

      • initInstance

        void initInstance​(java.lang.String mappedName,
                  java.lang.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​(java.lang.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​(java.lang.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

        java.lang.String createConfiguration​(java.lang.String sessionId,
                                     java.lang.String customTypeName,
                                     java.util.Map<java.lang.String,​java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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
java.lang.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