001    /**
002     * Copyright (c) 2000-2012 Liferay, Inc. All rights reserved.
003     *
004     * This library is free software; you can redistribute it and/or modify it under
005     * the terms of the GNU Lesser General Public License as published by the Free
006     * Software Foundation; either version 2.1 of the License, or (at your option)
007     * any later version.
008     *
009     * This library is distributed in the hope that it will be useful, but WITHOUT
010     * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
011     * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
012     * details.
013     */
014    
015    package com.liferay.portal.kernel.lar;
016    
017    import javax.portlet.PortletPreferences;
018    
019    /**
020     * A <code>PortletDataHandler</code> is a special class capable of exporting and
021     * importing portlet specific data to a Liferay Archive file (LAR) when a site's
022     * layouts are exported or imported. <code>PortletDataHandler</code>s are
023     * defined by placing a <code>portlet-data-handler-class</code> element in the
024     * <code>portlet</code> section of the <b>liferay-portlet.xml</b> file.
025     *
026     * @author Raymond Augé
027     * @author Joel Kozikowski
028     * @author Bruno Farache
029     */
030    public interface PortletDataHandler {
031    
032            /**
033             * Deletes the data created by the portlet. Can optionally return a modified
034             * version of <code>preferences</code> if it contains reference to data that
035             * does not exist anymore.
036             *
037             * @param  portletDataContext the context of the data deletion
038             * @param  portletId the portlet ID of the portlet
039             * @param  portletPreferences the portlet preferences of the portlet
040             * @return A modified version of portlet preferences that should be saved.
041             *         <code>Null</code> if the portlet preferences were unmodified by
042             *         this data handler.
043             * @throws PortletDataException if a portlet data exception occurred
044             */
045            public PortletPreferences deleteData(
046                            PortletDataContext portletDataContext, String portletId,
047                            PortletPreferences portletPreferences)
048                    throws PortletDataException;
049    
050            /**
051             * Returns a string of data to be placed in the &lt;portlet-data&gt; section
052             * of the LAR file. This data will be passed as the <code>data</code>
053             * parameter of <code>importData()</code>.
054             *
055             * @param  portletDataContext the context of the data export
056             * @param  portletId the portlet ID of the portlet
057             * @param  portletPreferences the portlet preferences of the portlet
058             * @return A string of data to be placed in the LAR. It may be XML, but not
059             *         necessarily. <code>Null</code> should be returned if no portlet
060             *         data is to be written out.
061             * @throws PortletDataException if a portlet data exception occurred
062             */
063            public String exportData(
064                            PortletDataContext portletDataContext, String portletId,
065                            PortletPreferences portletPreferences)
066                    throws PortletDataException;
067    
068            /**
069             * Returns an array of the portlet preferences that reference data. These
070             * preferences should only be updated if the referenced data is imported.
071             *
072             * @return A String array
073             */
074            public String[] getDataPortletPreferences();
075    
076            /**
077             * Returns an array of the controls defined for this data handler. These
078             * controls enable the developer to create fine grained controls over export
079             * behavior. The controls are rendered in the export UI.
080             *
081             * @return an array of PortletDataHandlerControls
082             * @throws PortletDataException if a portlet data exception occurred
083             */
084            public PortletDataHandlerControl[] getExportControls()
085                    throws PortletDataException;
086    
087            /**
088             * Returns an array of the metadata controls defined for this data handler.
089             * These controls enable the developer to create fine grained controls over
090             * export behavior of metadata such as tags, categories, ratings or
091             * comments. The controls are rendered in the export UI.
092             *
093             * @return an array of PortletDataHandlerControls
094             * @throws PortletDataException if a portlet data exception occurred
095             */
096            public PortletDataHandlerControl[] getExportMetadataControls()
097                    throws PortletDataException;
098    
099            /**
100             * Returns an array of the controls defined for this data handler. These
101             * controls enable the developer to create fine grained controls over import
102             * behavior. The controls are rendered in the import UI.
103             *
104             * @return An array of PortletDataHandlerControls
105             * @throws PortletDataException if a portlet data exception occurred
106             */
107            public PortletDataHandlerControl[] getImportControls()
108                    throws PortletDataException;
109    
110            /**
111             * Returns an array of the metadata controls defined for this data handler.
112             * These controls enable the developer to create fine grained controls over
113             * import behavior of metadata such as tags, categories, ratings or
114             * comments. The controls are rendered in the export UI.
115             *
116             * @return an array of PortletDataHandlerControls
117             * @throws PortletDataException if a portlet data exception occurred
118             */
119            public PortletDataHandlerControl[] getImportMetadataControls()
120                    throws PortletDataException;
121    
122            /**
123             * Handles any special processing of the data when the portlet is imported
124             * into a new layout. Can optionally return a modified version of
125             * <code>preferences</code> to be saved in the new portlet.
126             *
127             * @param  portletDataContext the context of the data import
128             * @param  portletId the portlet ID of the portlet
129             * @param  portletPreferences the portlet preferences of the portlet
130             * @param  data the string data that was returned by
131             *         <code>exportData()</code>
132             * @return A modified version of portlet preferences that should be saved.
133             *         <code>Null</code> if the portlet preferences were unmodified by
134             *         this data handler.
135             * @throws PortletDataException if a portlet data exception occurred
136             */
137            public PortletPreferences importData(
138                            PortletDataContext portletDataContext, String portletId,
139                            PortletPreferences portletPreferences, String data)
140                    throws PortletDataException;
141    
142            /**
143             * Returns <code>true</code> to allow the user to export data for this
144             * portlet even though it may not belong to any pages. See LPS-1624.
145             *
146             * @return <code>true</code> to allow the user to export data for this
147             *         portlet even though it may not belong to any pages
148             */
149            public boolean isAlwaysExportable();
150    
151            public boolean isAlwaysStaged();
152    
153            public boolean isDataLocalized();
154    
155            /**
156             * Returns whether the data exported by this handler should be included by
157             * default when publishing to live. This should only be <code>true</code>
158             * for data that is meant to be managed in an staging environment such as
159             * CMS content, but not for data meant to be input by users such as wiki
160             * pages or message board posts.
161             *
162             * @return <code>true</code> to publish to live by default
163             */
164            public boolean isPublishToLiveByDefault();
165    
166    }