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