| PortletDataHandler.java |
1 /**
2 * Copyright (c) 2000-2009 Liferay, Inc. All rights reserved.
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining a copy
5 * of this software and associated documentation files (the "Software"), to deal
6 * in the Software without restriction, including without limitation the rights
7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 * copies of the Software, and to permit persons to whom the Software is
9 * furnished to do so, subject to the following conditions:
10 *
11 * The above copyright notice and this permission notice shall be included in
12 * all copies or substantial portions 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 */
44 public interface PortletDataHandler {
45
46 /**
47 * Deletes the data created by the portlet. Can optionally return a modified
48 * version of <code>preferences</code> if it contains reference to data that
49 * does not exist anymore.
50 *
51 * @param context the context of the data deletion
52 * @param portletId the portlet id of the portlet
53 * @param preferences the portlet preferences of the portlet
54 *
55 * @return A modified version of preferences that should be saved. Null
56 * if the preferences were unmodified by this data handler.
57 * @throws PortletDataException
58 */
59 public PortletPreferences deleteData(
60 PortletDataContext context, String portletId,
61 PortletPreferences preferences)
62 throws PortletDataException;
63
64 /**
65 * Returns a string of data to be placed in the <portlet-data> section
66 * of the LAR file. This data will be passed as the <code>data</code>
67 * parameter of <code>importData()</code>.
68 *
69 * @param context the context of the data export
70 * @param portletId the portlet id of the portlet
71 * @param preferences the portlet preferences of the portlet
72 * @return A string of data to be placed in the LAR. It may be XML,
73 * but not necessarily. Null should be returned if no portlet
74 * data is to be written out.
75 * @throws PortletDataException
76 */
77 public String exportData(
78 PortletDataContext context, String portletId,
79 PortletPreferences preferences)
80 throws PortletDataException;
81
82 /**
83 * Returns an array of the controls defined for this data handler. These
84 * controls enable the developer to create fine grained controls over export
85 * behavior. The controls are rendered in the export UI.
86 *
87 * @return an array of PortletDataHandlerControls
88 */
89 public PortletDataHandlerControl[] getExportControls()
90 throws PortletDataException;
91
92 /**
93 * Returns an array of the controls defined for this data handler. These
94 * controls enable the developer to create fine grained controls over import
95 * behavior. The controls are rendered in the import UI.
96 *
97 * @return An array of PortletDataHandlerControls
98 */
99 public PortletDataHandlerControl[] getImportControls()
100 throws PortletDataException;
101
102 /**
103 * Handles any special processing of the data when the portlet is imported
104 * into a new layout. Can optionally return a modified version of
105 * <code>preferences</code> to be saved in the new portlet.
106 *
107 * @param context the context of the data import
108 * @param portletId the portlet id of the portlet
109 * @param preferences the portlet preferences of the portlet
110 * @param data the string data that was returned by
111 * <code>exportData()</code>
112 * @return A modified version of preferences that should be
113 * saved. Null if the preferences were unmodified by this data
114 * handler.
115 * @throws PortletDataException
116 */
117 public PortletPreferences importData(
118 PortletDataContext context, String portletId,
119 PortletPreferences preferences, String data)
120 throws PortletDataException;
121
122 /**
123 * Returns true to allow the user to export data for this portlet even
124 * though it may not belong to any pages. See LPS-1624.
125 *
126 * @return true to allow the user to export data for this portlet even
127 * though it may not belong to any pages
128 */
129 public boolean isAlwaysExportable();
130
131 /**
132 * Returns whether the data exported by this handler should be included
133 * by default when publishing to live. This should only be true for data
134 * that is meant to be managed in an staging environment such as CMS
135 * content, but not for data meant to be input by users such as wiki pages
136 * or message board posts.
137 *
138 * @return true to publish to live by default
139 */
140 public boolean isPublishToLiveByDefault();
141
142 }