1   /**
2    * Copyright (c) 2000-2007 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.kernel.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   *
42   */
43  public interface PortletDataHandler {
44  
45      /**
46       * Returns an array of the controls defined for this data handler. These
47       * controls enable the developer to create fine grained controls over export
48       * behavior. The controls are rendered in the export UI.
49       *
50       * @return      an array of PortletDataHandlerControls
51       */
52      public PortletDataHandlerControl[] getExportControls()
53          throws PortletDataException;
54  
55      /**
56       * Returns an array of the controls defined for this data handler. These
57       * controls enable the developer to create fine grained controls over import
58       * behavior. The controls are rendered in the import UI.
59       *
60       * @return      An array of PortletDataHandlerControls
61       */
62      public PortletDataHandlerControl[] getImportControls()
63          throws PortletDataException;
64  
65      /**
66       * Returns a string of data to be placed in the &lt;portlet-data&gt; section
67       * of the LAR file. This data will be passed as the <code>data</code>
68       * parameter of <code>importData()</code>.
69       *
70       * @param       context the context of the data export
71       * @param       portletId the portlet id of the portlet
72       * @param       prefs the portlet preferences of the portlet
73       * @return      A string of data to be placed in the LAR. It may be XML,
74       *              but not necessarily. Null should be returned if no portlet
75       *              data is to be written out.
76       * @throws      PortletDataException
77       */
78      public String exportData(
79              PortletDataContext context, String portletId,
80              PortletPreferences prefs)
81          throws PortletDataException;
82  
83      /**
84       * Handles any special processing of the data when the portlet is imported
85       * into a new layout. Can optionally return a modified version of
86       * <code>prefs</code> to be saved in the new portlet.
87       *
88       * @param       context the context of the data import
89       * @param       portletId the portlet id of the portlet
90       * @param       prefs the portlet preferences of the portlet
91       * @param       data the string data that was returned by
92       *              <code>exportData()</code>
93       * @return      A modified version of prefs that should be
94       *              saved. Null if the preferences were unmodified by this data
95       *              handler.
96       * @throws PortletDataException
97       */
98      public PortletPreferences importData(
99              PortletDataContext context, String portletId,
100             PortletPreferences prefs, String data)
101         throws PortletDataException;
102 
103 }