| PortletDataHandler.java |
1 /**
2 * Copyright (c) 2000-2010 Liferay, Inc. All rights reserved.
3 *
4 * This library is free software; you can redistribute it and/or modify it under
5 * the terms of the GNU Lesser General Public License as published by the Free
6 * Software Foundation; either version 2.1 of the License, or (at your option)
7 * any later version.
8 *
9 * This library is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
11 * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
12 * details.
13 */
14
15 package com.liferay.portal.lar;
16
17 import javax.portlet.PortletPreferences;
18
19 /**
20 * <a href="PortletDataHandler.java.html"><b><i>View Source</i></b></a>
21 *
22 * <p>
23 * A <code>PortletDataHandler</code> is a special class capable of exporting and
24 * importing portlet specific data to a Liferay Archive file (LAR) when a
25 * community's layouts are exported or imported.
26 * <code>PortletDataHandler</code>s are defined by placing a
27 * <code>portlet-data-handler-class</code> element in the <code>portlet</code>
28 * section of the <b>liferay-portlet.xml</b> file.
29 * </p>
30 *
31 * @author Raymond Augé
32 * @author Joel Kozikowski
33 * @author Bruno Farache
34 */
35 public interface PortletDataHandler {
36
37 /**
38 * Deletes the data created by the portlet. Can optionally return a modified
39 * version of <code>preferences</code> if it contains reference to data that
40 * does not exist anymore.
41 *
42 * @param context the context of the data deletion
43 * @param portletId the portlet id of the portlet
44 * @param preferences the portlet preferences of the portlet
45 * @return A modified version of preferences that should be saved. Null if
46 * the preferences were unmodified by this data handler.
47 */
48 public PortletPreferences deleteData(
49 PortletDataContext context, String portletId,
50 PortletPreferences preferences)
51 throws PortletDataException;
52
53 /**
54 * Returns a string of data to be placed in the <portlet-data> section
55 * of the LAR file. This data will be passed as the <code>data</code>
56 * parameter of <code>importData()</code>.
57 *
58 * @param context the context of the data export
59 * @param portletId the portlet id of the portlet
60 * @param preferences the portlet preferences of the portlet
61 * @return A string of data to be placed in the LAR. It may be XML, but not
62 * necessarily. Null should be returned if no portlet data is to be
63 * written out.
64 */
65 public String exportData(
66 PortletDataContext context, String portletId,
67 PortletPreferences preferences)
68 throws PortletDataException;
69
70 /**
71 * Returns an array of the controls defined for this data handler. These
72 * controls enable the developer to create fine grained controls over export
73 * behavior. The controls are rendered in the export UI.
74 *
75 * @return an array of PortletDataHandlerControls
76 */
77 public PortletDataHandlerControl[] getExportControls()
78 throws PortletDataException;
79
80 /**
81 * Returns an array of the controls defined for this data handler. These
82 * controls enable the developer to create fine grained controls over import
83 * behavior. The controls are rendered in the import UI.
84 *
85 * @return An array of PortletDataHandlerControls
86 */
87 public PortletDataHandlerControl[] getImportControls()
88 throws PortletDataException;
89
90 /**
91 * Handles any special processing of the data when the portlet is imported
92 * into a new layout. Can optionally return a modified version of
93 * <code>preferences</code> to be saved in the new portlet.
94 *
95 * @param context the context of the data import
96 * @param portletId the portlet id of the portlet
97 * @param preferences the portlet preferences of the portlet
98 * @param data the string data that was returned by
99 * <code>exportData()</code>
100 * @return A modified version of preferences that should be saved. Null if
101 * the preferences were unmodified by this data handler.
102 */
103 public PortletPreferences importData(
104 PortletDataContext context, String portletId,
105 PortletPreferences preferences, String data)
106 throws PortletDataException;
107
108 /**
109 * Returns true to allow the user to export data for this portlet even
110 * though it may not belong to any pages. See LPS-1624.
111 *
112 * @return true to allow the user to export data for this portlet even
113 * though it may not belong to any pages
114 */
115 public boolean isAlwaysExportable();
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 }