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