1 /*
2 * Copyright (C) 2003-2008 eXo Platform SAS.
3 *
4 * This program is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Affero General Public License
6 * as published by the Free Software Foundation; either version 3
7 * of the License, or (at your option) any later version.
8 *
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
13 *
14 * You should have received a copy of the GNU General Public License
15 * along with this program; if not, see<http://www.gnu.org/licenses/>.
16 */
17 package org.exoplatform.services.ecm.publication;
18
19 import java.util.HashMap;
20 import java.util.Locale;
21 import java.util.Map;
22
23 import javax.jcr.Node;
24
25 /**
26 * Created by The eXo Platform SAS
27 * Author : Romain Dénarié
28 * romain.denarie@exoplatform.com
29 * 7 mai 08
30 */
31 public interface PublicationService {
32
33 public static final String PUBLICATION = "publication:publication";
34 public static final String LIFECYCLE_NAME = "publication:lifecycleName";
35 public static final String CURRENT_STATE = "publication:currentState";
36 public static final String HISTORY = "publication:history";
37
38 /**
39 * Add a Publication Plugin to the service.
40 * The method caches all added plugins.
41 *
42 * @param p the plugin to add
43 */
44 public void addPublicationPlugin(PublicationPlugin p);
45
46 /**
47 * Retrieves all added publication plugins.
48 * This method is notably used to enumerate possible lifecycles.
49 *
50 * @return the added publication plugins
51 */
52 public Map<String,PublicationPlugin> getPublicationPlugins();
53
54
55 /**
56 * Update the state of the specified node.
57 * This method first inspects the publication mixin bound to the specified
58 * Node. From that mixin, it retrieves the lifecycle registered with the
59 * node. Finally, it delegates the call to the method with same name in the
60 * plugin that implements the lifecycle.
61 *
62 * @param node the Node whose state needs to be changed
63 * @param newState the new state.
64 * @param context a Hashmap containing contextual information needed
65 * to change the state. The information set is defined on a State basis.
66 * A typical example is information submitted by the user in a user
67 * interface.
68 *
69 * @throws NotInPublicationLifecycleException in case the Node has not
70 * been registered in any lifecycle yet (in other words, if no publication
71 * mixin has been found).
72 * @throws IncorrectStateUpdateLifecycleException if the update is not
73 * allowed
74 * @throws Exception the exception
75 */
76 public void changeState(Node node, String newState, HashMap<String, String> context)
77 throws NotInPublicationLifecycleException, IncorrectStateUpdateLifecycleException, Exception;
78
79 /**
80 * Retrieves an image showing the lifecycle state of the specified Node.
81 * The method first inspects the specified Node. If it does not contain
82 * a publication mixin, then it throws a NotInPublicationLifecycleException
83 * exception. Else, it retrieves the lifecycle name from the mixin,
84 * selects the appropriate publication plugin and delegates the call to it.
85 *
86 * @param node the node from which the image should be obtained
87 * @param locale the locale
88 *
89 * @return an array of bytes corresponding to the image to be shown to the
90 * user
91 *
92 * @throws NotInPublicationLifecycleException in case the Node has not
93 * been registered in any lifecycle yet (in other words, if no publication
94 * mixin has been found).
95 * @throws Exception the exception
96 */
97 public byte[] getStateImage(Node node,Locale locale)throws NotInPublicationLifecycleException ,Exception;
98
99 /**
100 * Retrieves the name of the publication state corresponding to the
101 * specified Node.
102 * This method first inspects the specified Node. If it does not contain
103 * a publication mixin, then it throws a NotInPublicationLifecycleException
104 * exception. Else, it retrieves the current state name from the mixin.
105 * Possible examples of State names are : "draft", "validation requested",
106 * "publication pending", "published", "backed up", "validation refused".
107 *
108 * @param node the node from which the publication state should be retrieved
109 *
110 * @return a String giving the current state.
111 *
112 * @throws NotInPublicationLifecycleException in case the Node has not
113 * been registered in any lifecycle yet (in other words, if no publication
114 * mixin has been found).
115 * @throws Exception the exception
116 */
117 public String getCurrentState(Node node) throws NotInPublicationLifecycleException ,Exception;
118
119 /**
120 * Retrieves description information explaining to the user the current
121 *
122 * This method first inspects the specified Node. If it does not contain
123 * a publication mixin, then it throws a NotInPublicationLifecycleException
124 * exception. Else, it retrieves the lifecycle name from the mixin,
125 * selects the appropriate publication plugin and delegates the call to it.
126 *
127 * @param node the Node from which user information should be retrieved
128 * @param locale the locale
129 *
130 * @return a text message describing the state of the current message.
131 *
132 * @throws NotInPublicationLifecycleException in case the Node has not
133 * been registered in any lifecycle yet (in other words, if no publication
134 * mixin has been found).
135 * @throws Exception the exception
136 */
137 public String getUserInfo(Node node, Locale locale) throws NotInPublicationLifecycleException ,Exception;
138
139 /**
140 * Retrieves the history of publication changes made to the specified Node.
141 *
142 * This method first inspects the specified Node. If it does not contain
143 * a publication mixin, then it throws a NotInPublicationLifecycleException
144 * exception. Else, it retrieves the lifecycle name from the mixin,
145 * selects the appropriate publication plugin and delegates the call to it.
146 *
147 * Log entries are specified as a multi-valued property of the publication
148 * mixin.
149 *
150 * @param node the Node from which the history Log should be retrieved
151 *
152 * @return a String array with 2 dimensions. The first dimension contains
153 * each log entry. The second dimension contains each information in a log
154 * entry, which are : date, name of the new state, involved user, additional
155 * information.
156 *
157 * @throws NotInPublicationLifecycleException in case the Node has not
158 * been registered in any lifecycle yet (in other words, if no publication
159 * mixin has been found).
160 * @throws Exception the exception
161 */
162 public String[][] getLog(Node node) throws NotInPublicationLifecycleException, Exception;
163
164 /**
165 * Adds the log.
166 *
167 * @param node the node
168 * @param log the log
169 *
170 * @throws NotInPublicationLifecycleException the not in publication lifecycle exception
171 * @throws Exception the exception
172 */
173
174
175 /**
176 * Adds a log entry to the specified Node. The specified array of String
177 * defines the Log information to be added. Log entries are specified as a
178 * multi-valued property of the publication mixin.
179 *
180 * @param node the Node from which the history Log should be updated
181 * @param log the Log information to be added log contains : date, newState,
182 * userInvolved, key for additionalInformation in locale with
183 * possible subsitutions, values for substitutions
184 * @throws NotInPublicationLifecycleException in case the Node has not been
185 * registered in any lifecycle yet (in other words, if no
186 * publication mixin has been found).
187 * @throws Exception the exception
188 */
189 public void addLog(Node node, String[] log) throws NotInPublicationLifecycleException, Exception;
190
191 /**
192 * Determines whether the specified Node has been enrolled into a
193 * lifecycle.
194 *
195 * @param node the Node from which the enrollment should be evaluated
196 *
197 * @return true of the Node is enrolled
198 *
199 * @throws Exception the exception
200 */
201 public boolean isNodeEnrolledInLifecycle(Node node) throws Exception;
202
203 /**
204 * Retrieves the name of the lifecycle in which the specified Node has
205 * been enrolled.
206 *
207 * @param node the Node from which the enrollment should be retrieved
208 *
209 * @return the name of the lifecycle corresponding to the specified Node
210 *
211 * @throws NotInPublicationLifecycleException in case the Node has not
212 * been registered in any lifecycle yet (in other words, if no publication
213 * mixin has been found).
214 * @throws Exception the exception
215 */
216 public String getNodeLifecycleName(Node node) throws NotInPublicationLifecycleException, Exception;
217
218 /**
219 * Retrieves the description of the lifecycle in which the specified Node
220 * has been enrolled.
221 *
222 * This method first inspects the specified Node. If it does not contain
223 * a publication mixin, then it throws a NotInPublicationLifecycleException
224 * exception. Else, it retrieves the lifecycle name from the mixin,
225 * selects the appropriate publication plugin and delegates the call to it.
226 *
227 * @param node the Node from which the enrollment should be retrieved
228 *
229 * @return the description of the lifecycle corresponding to the specified
230 * Node
231 *
232 * @throws NotInPublicationLifecycleException in case the Node has not
233 * been registered in any lifecycle yet (in other words, if no publication
234 * mixin has been found).
235 * @throws Exception the exception
236 */
237 public String getNodeLifecycleDesc(Node node) throws NotInPublicationLifecycleException ,Exception;
238
239 /**
240 * Enroll the specified Node to the specified lifecycle.
241 * This method adds a publication mixin to the specified Node. The lifecycle
242 * name is the one specified as parameter. By default, the state is set
243 * to "enrolled".
244 *
245 * @param node the Node to be enrolled in the specified lifecycle
246 * @param lifecycle the name of the lifecycle in which the Node should be
247 * enrolled
248 *
249 * @throws AlreadyInPublicationLifecycleException the already in publication lifecycle exception
250 * @throws Exception the exception
251 */
252 public void enrollNodeInLifecycle(Node node, String lifecycle) throws AlreadyInPublicationLifecycleException, Exception;
253
254 /**
255 * Unsubcribe node that in publication lifecyle.
256 *
257 * @param node the node
258 *
259 * @throws NotInPublicationLifecycleException the not in publication lifecycle exception
260 * @throws Exception the exception
261 */
262 public void unsubcribeLifecycle(Node node) throws NotInPublicationLifecycleException, Exception;
263
264 /**
265 * Check current node is unsubcriber or nots
266 * @param node
267 * @return
268 * - true: this node is unsubcriber Lifecycle
269 * - false: this node is not unsubcriber Lifecycle
270 * @throws Exception
271 */
272 public boolean isUnsubcribeLifecycle(Node node) throws Exception;
273
274 /**
275 * Get localized log messages and substitute variables.
276 *
277 * @param locale : the locale to use
278 * @param key : the key to translate
279 * @param values : array of string to susbtitute in the string
280 *
281 * @return a string localized and where values are substitute
282 */
283 public String getLocalizedAndSubstituteLog(Locale locale, String key, String[] values);
284
285 /**
286 * Gets the localized and substitute log for current node.
287 * Base on lifecycle that node is enroll. The method call to get message for each lifecycle
288 *
289 * @param node the node
290 * @param locale the locale
291 * @param key the key
292 * @param values the values
293 *
294 * @return the localized and substitute log
295 *
296 * @throws NotInPublicationLifecycleException the not in publication lifecycle exception
297 * @throws Exception the exception
298 */
299 public String getLocalizedAndSubstituteLog(Node node,
300 Locale locale,
301 String key,
302 String[] values) throws NotInPublicationLifecycleException,
303 Exception;
304
305 public Node getNodePublish(Node node, String pluginName) throws Exception;
306 }