| PortletDataHandler.java |
1 /**
2 * Copyright (c) 2000-2009 Liferay, Inc. All rights reserved.
3 *
4 *
5 *
6 *
7 * The contents of this file are subject to the terms of the Liferay Enterprise
8 * Subscription License ("License"). You may not use this file except in
9 * compliance with the License. You can obtain a copy of the License by
10 * contacting Liferay, Inc. See the License for the specific language governing
11 * permissions and limitations under the License, including but not limited to
12 * distribution rights of the Software.
13 *
14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
20 * SOFTWARE.
21 */
22
23 package com.liferay.portal.lar;
24
25 import javax.portlet.PortletPreferences;
26
27 /**
28 * <a href="PortletDataHandler.java.html"><b><i>View Source</i></b></a>
29 *
30 * <p>
31 * A <code>PortletDataHandler</code> is a special class capable of exporting and
32 * importing portlet specific data to a Liferay Archive file (LAR) when a
33 * community's layouts are exported or imported.
34 * <code>PortletDataHandler</code>s are defined by placing a
35 * <code>portlet-data-handler-class</code> element in the <code>portlet</code>
36 * section of the <b>liferay-portlet.xml</b> file.
37 * </p>
38 *
39 * @author Raymond Augé
40 * @author Joel Kozikowski
41 * @author Bruno Farache
42 */
43 public interface PortletDataHandler {
44
45 /**
46 * Deletes the data created by the portlet. Can optionally return a modified
47 * version of <code>prefs</code> if it contains reference to data that does
48 * not exist anymore.
49 *
50 * @param context the context of the data deletion
51 * @param portletId the portlet id of the portlet
52 * @param prefs the portlet preferences of the portlet
53 * @return A modified version of prefs that should be saved. Null if
54 * the preferences were unmodified by this data handler.
55 */
56 public PortletPreferences deleteData(
57 PortletDataContext context, String portletId,
58 PortletPreferences prefs)
59 throws PortletDataException;
60
61 /**
62 * Returns a string of data to be placed in the <portlet-data> section
63 * of the LAR file. This data will be passed as the <code>data</code>
64 * parameter of <code>importData()</code>.
65 *
66 * @param context the context of the data export
67 * @param portletId the portlet id of the portlet
68 * @param prefs the portlet preferences of the portlet
69 * @return A string of data to be placed in the LAR. It may be XML,
70 * but not necessarily. Null should be returned if no portlet
71 * data is to be written out.
72 */
73 public String exportData(
74 PortletDataContext context, String portletId,
75 PortletPreferences prefs)
76 throws PortletDataException;
77
78 /**
79 * Returns an array of the controls defined for this data handler. These
80 * controls enable the developer to create fine grained controls over export
81 * behavior. The controls are rendered in the export UI.
82 *
83 * @return an array of PortletDataHandlerControls
84 */
85 public PortletDataHandlerControl[] getExportControls()
86 throws PortletDataException;
87
88 /**
89 * Returns an array of the controls defined for this data handler. These
90 * controls enable the developer to create fine grained controls over import
91 * behavior. The controls are rendered in the import UI.
92 *
93 * @return An array of PortletDataHandlerControls
94 */
95 public PortletDataHandlerControl[] getImportControls()
96 throws PortletDataException;
97
98 /**
99 * Handles any special processing of the data when the portlet is imported
100 * into a new layout. Can optionally return a modified version of
101 * <code>prefs</code> to be saved in the new portlet.
102 *
103 * @param context the context of the data import
104 * @param portletId the portlet id of the portlet
105 * @param prefs the portlet preferences of the portlet
106 * @param data the string data that was returned by
107 * <code>exportData()</code>
108 * @return A modified version of prefs that should be
109 * saved. Null if the preferences were unmodified by this data
110 * handler.
111 */
112 public PortletPreferences importData(
113 PortletDataContext context, String portletId,
114 PortletPreferences prefs, String data)
115 throws PortletDataException;
116
117 /**
118 * Returns whether the data exported by this handler should be included by
119 * default when publishing to live. This should only be true for data that
120 * is meant to be managed in an staging environment such as CMS content, but
121 * not for data meant to be input by users such as wiki pages or message
122 * board posts.
123 *
124 * @return true to publish to live by default
125 */
126 public boolean isPublishToLiveByDefault();
127
128 }