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 &lt;portlet-data&gt; 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 }