/*
* Copyright (C) 2003-2008 eXo Platform SAS.
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU Affero General Public License
* as published by the Free Software Foundation; either version 3
* of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, see<http://www.gnu.org/licenses/>.
*/
package org.exoplatform.services.ecm.publication;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import javax.jcr.Node;
import org.exoplatform.container.component.BaseComponentPlugin;
import org.exoplatform.webui.core.UIComponent;
import org.exoplatform.webui.form.UIForm;
/**
* Base class of Publication plugins.
* Publication plugins implement a publication lifecycle. Each time a new
* custom lifecycle needs to be defined, a new plugin has to be implemented
* and registered with the Publication Service.
*
* The getName() method in the parent class is used to identify the lifecycle.
* The getDescription() method in the parent class is used to describe the
* lifecycle. Internationalization resource bundles are used in the
* implementation of the method.
*/
public abstract class PublicationPlugin extends BaseComponentPlugin {
/**
* Retrieves all possible states in the publication lifecycle.
*
* @return an array of Strings giving the names of all possible states
*/
public abstract String[] getPossibleStates();
/**
* Change the state of the specified Node.
* The implementation of this method basically retrieves the current
* state from the publication mixin of the specified Node. Then, based on
* the newState, it is able to determine if the update is possible. If
* yes, appropriate action is made (eg: launch a publication workflow). In
* all cases, the current state information is updated in the publication
* mixin of the specified Node.
*
* @param node the Node whose state needs to be changed
* @param newState the new state.
* @param context a Hashmap containing contextual information needed
* to change the state. The information set is defined on a State basis.
*
* @throws IncorrectStateUpdateLifecycleException if the update is not
* allowed
* @throws Exception the exception
*/
public abstract void changeState(Node node,
String newState,
HashMap<String, String> context)
throws IncorrectStateUpdateLifecycleException, Exception;
/**
* Retrieves the WebUI form corresponding to the current state of the
* specified node.
* There are two cases here. Either the form contains read only fields (when
* the state is supposed to be processed by an external entity such as a
* Workflow). Or the form has editable fields or buttons (in the case the
* user can interfere. In that case, some action listeners are leveraged.).
* In all cases, all UI and listener classes are provided in the JAR
* corresponding to the PublicationPlugin.
* The method first inspects the specified Node. If it does not contain
* a publication mixin, then it throws a NotInPublicationLifecycleException
* exception. Else, it retrieves the lifecycle name from the mixin,
* selects the appropriate publication plugin and delegates the call to it.
*
* @param node the Node from which the state UI should be retrieved
* @param component the component
*
* @return a WebUI form corresponding to the current state and node.
*
* @throws Exception the exception
*/
public abstract UIForm getStateUI(Node node, UIComponent component) throws Exception;
/**
* Retrieves an image showing the lifecycle state of the specified Node.
* The implementation of this method typically retrieves the current state
* of the specified Node, then fetches the bytes of an appropriate image
* found in the jar of the plugin. This image is supposed to be shown in
* the publication dialog of the JCR File Explorer Portlet.
*
* @param node the node from which the image should be obtained
* @param locale the locale
*
* @return an array of bytes corresponding to the image to be shown to the
* user
*
* @throws IOException Signals that an I/O exception has occurred.
* @throws FileNotFoundException the file not found exception
* @throws Exception the exception
*/
public abstract byte[] getStateImage(Node node, Locale locale) throws IOException,FileNotFoundException,Exception;
/**
* Retrieves description information explaining to the user the current
* publication state of the specified Node. Possible examples are
* - "The document has been submitted to the following group for validation:
* /organization/management.".
* - "The document has been validated and will be published from
* May 3rd 10:00am to May 3rd 10:00pm. At that time, it will be unpublished
* and put in a backup state.".
* - "The document is in draft state. At any time you can turn it to
* published state."
*
* The returned message should be obtained from internationalization
* resource bundles (ie not hardcoded).
*
* @param node the node from which the publication state should be retrieved
* @param locale the locale
*
* @return a String giving the current state.
*
* @throws Exception the exception
*/
public abstract String getUserInfo(Node node, Locale locale) throws Exception;
/**
* Retrieves the lifecycleName.
*
* @return a String giving the lifecycleName
*/
public String getLifecycleName() {
return getName();
}
/**
* Retrieves the description of the plugin.
*
* @param node the node
*
* @return a String giving the description
*/
public String getNodeLifecycleDesc(Node node) {
return getDescription();
}
/**
* Return if the plugin can add the specific mixin for the publication.
*
* @param node the node to add the mixin
*
* @return boolean
*
* @throws Exception the exception
*/
public abstract boolean canAddMixin (Node node) throws Exception;
/**
* Add the specific plugin mixin to the node.
*
* @param node the node
*
* @throws Exception the exception
*/
public abstract void addMixin (Node node) throws Exception;
/**
* Retrieves a node view of the specific node in a context
*
* @param node the node
* @param context the context
*
* @return the node to view
*
* @throws Exception the exception
*/
public abstract Node getNodeView(Node node, Map<String,Object> context) throws Exception;
/**
* Get localized log messages and substitute variables.
*
* @param locale : the locale to use
* @param key : the key to translate
* @param values : array of string to susbtitute in the string
*
* @return a string localized and where values are substitute
*/
public abstract String getLocalizedAndSubstituteMessage(Locale locale, String key, String[] values) throws Exception;
}