001    /**
002     * Copyright (c) 2000-2013 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 com.liferay.portal.kernel.xml.Element;
018    import com.liferay.portal.model.Portlet;
019    
020    import javax.portlet.PortletPreferences;
021    
022    /**
023     * A <code>PortletDataHandler</code> is a special class capable of exporting and
024     * importing portlet specific data to a Liferay Archive file (LAR) when a site's
025     * layouts are exported or imported. <code>PortletDataHandler</code>s are
026     * defined by placing a <code>portlet-data-handler-class</code> element in the
027     * <code>portlet</code> section of the <b>liferay-portlet.xml</b> file.
028     *
029     * @author Raymond Aug??
030     * @author Joel Kozikowski
031     * @author Bruno Farache
032     */
033    public interface PortletDataHandler {
034    
035            /**
036             * Deletes the data created by the portlet. Can optionally return a modified
037             * version of <code>preferences</code> if it contains reference to data that
038             * does not exist anymore.
039             *
040             * @param  portletDataContext the context of the data deletion
041             * @param  portletId the portlet ID of the portlet
042             * @param  portletPreferences the portlet preferences of the portlet
043             * @return A modified version of portlet preferences that should be saved.
044             *         <code>Null</code> if the portlet preferences were unmodified by
045             *         this data handler.
046             * @throws PortletDataException if a portlet data exception occurred
047             */
048            public PortletPreferences deleteData(
049                            PortletDataContext portletDataContext, String portletId,
050                            PortletPreferences portletPreferences)
051                    throws PortletDataException;
052    
053            /**
054             * Returns a string of data to be placed in the &lt;portlet-data&gt; section
055             * of the LAR file. This data will be passed as the <code>data</code>
056             * parameter of <code>importData()</code>.
057             *
058             * @param  portletDataContext the context of the data export
059             * @param  portletId the portlet ID of the portlet
060             * @param  portletPreferences the portlet preferences of the portlet
061             * @return A string of data to be placed in the LAR. It may be XML, but not
062             *         necessarily. <code>Null</code> should be returned if no portlet
063             *         data is to be written out.
064             * @throws PortletDataException if a portlet data exception occurred
065             */
066            public String exportData(
067                            PortletDataContext portletDataContext, String portletId,
068                            PortletPreferences portletPreferences)
069                    throws PortletDataException;
070    
071            public DataLevel getDataLevel();
072    
073            /**
074             * Returns an array of the portlet preferences that reference data. These
075             * preferences should only be updated if the referenced data is imported.
076             *
077             * @return A String array
078             */
079            public String[] getDataPortletPreferences();
080    
081            public StagedModelType[] getDeletionSystemEventStagedModelTypes();
082    
083            public PortletDataHandlerControl[] getExportConfigurationControls(
084                            long companyId, long groupId, Portlet portlet,
085                            boolean privateLayout)
086                    throws Exception;
087    
088            public PortletDataHandlerControl[] getExportConfigurationControls(
089                            long companyId, long groupId, Portlet portlet, long plid,
090                            boolean privateLayout)
091                    throws Exception;
092    
093            /**
094             * Returns an array of the controls defined for this data handler. These
095             * controls enable the developer to create fine grained controls over export
096             * behavior. The controls are rendered in the export UI.
097             *
098             * @return an array of PortletDataHandlerControls
099             * @throws PortletDataException if a portlet data exception occurred
100             */
101            public PortletDataHandlerControl[] getExportControls()
102                    throws PortletDataException;
103    
104            /**
105             * Returns an array of the metadata controls defined for this data handler.
106             * These controls enable the developer to create fine grained controls over
107             * export behavior of metadata such as tags, categories, ratings or
108             * comments. The controls are rendered in the export UI.
109             *
110             * @return an array of PortletDataHandlerControls
111             * @throws PortletDataException if a portlet data exception occurred
112             */
113            public PortletDataHandlerControl[] getExportMetadataControls()
114                    throws PortletDataException;
115    
116            public long getExportModelCount(ManifestSummary manifestSummary);
117    
118            public PortletDataHandlerControl[] getImportConfigurationControls(
119                    Portlet portlet, ManifestSummary manifestSummary);
120    
121            public PortletDataHandlerControl[] getImportConfigurationControls(
122                    String[] configurationPortletOptions);
123    
124            /**
125             * Returns an array of the controls defined for this data handler. These
126             * controls enable the developer to create fine grained controls over import
127             * behavior. The controls are rendered in the import UI.
128             *
129             * @return An array of PortletDataHandlerControls
130             * @throws PortletDataException if a portlet data exception occurred
131             */
132            public PortletDataHandlerControl[] getImportControls()
133                    throws PortletDataException;
134    
135            /**
136             * Returns an array of the metadata controls defined for this data handler.
137             * These controls enable the developer to create fine grained controls over
138             * import behavior of metadata such as tags, categories, ratings or
139             * comments. The controls are rendered in the export UI.
140             *
141             * @return an array of PortletDataHandlerControls
142             * @throws PortletDataException if a portlet data exception occurred
143             */
144            public PortletDataHandlerControl[] getImportMetadataControls()
145                    throws PortletDataException;
146    
147            public String getPortletId();
148    
149            /**
150             * Handles any special processing of the data when the portlet is imported
151             * into a new layout. Can optionally return a modified version of
152             * <code>preferences</code> to be saved in the new portlet.
153             *
154             * @param  portletDataContext the context of the data import
155             * @param  portletId the portlet ID of the portlet
156             * @param  portletPreferences the portlet preferences of the portlet
157             * @param  data the string data that was returned by
158             *         <code>exportData()</code>
159             * @return A modified version of portlet preferences that should be saved.
160             *         <code>Null</code> if the portlet preferences were unmodified by
161             *         this data handler.
162             * @throws PortletDataException if a portlet data exception occurred
163             */
164            public PortletPreferences importData(
165                            PortletDataContext portletDataContext, String portletId,
166                            PortletPreferences portletPreferences, String data)
167                    throws PortletDataException;
168    
169            public boolean isDataLocalized();
170    
171            public boolean isDataPortalLevel();
172    
173            public boolean isDataPortletInstanceLevel();
174    
175            public boolean isDataSiteLevel();
176    
177            /**
178             * Returns whether the data exported by this handler should be included by
179             * default when publishing to live. This should only be <code>true</code>
180             * for data that is meant to be managed in an staging environment such as
181             * CMS content, but not for data meant to be input by users such as wiki
182             * pages or message board posts.
183             *
184             * @return <code>true</code> to publish to live by default
185             */
186            public boolean isPublishToLiveByDefault();
187    
188            public boolean isSupportsDataStrategyCopyAsNew();
189    
190            public void prepareManifestSummary(PortletDataContext portletDataContext)
191                    throws PortletDataException;
192    
193            public void prepareManifestSummary(
194                            PortletDataContext portletDataContext,
195                            PortletPreferences portletPreferences)
196                    throws PortletDataException;
197    
198            public PortletPreferences processExportPortletPreferences(
199                            PortletDataContext portletDataContext, String portletId,
200                            PortletPreferences portletPreferences, Element rootElement)
201                    throws PortletDataException;
202    
203            public PortletPreferences processImportPortletPreferences(
204                            PortletDataContext portletDataContext, String portletId,
205                            PortletPreferences portletPreferences)
206                    throws PortletDataException;
207    
208            public void setPortletId(String portletId);
209    
210    }