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                    throws PortletDataException;
121    
122            /**
123             * Returns an array of the controls defined for this data handler. These
124             * controls enable the developer to create fine grained controls over import
125             * behavior. The controls are rendered in the import UI.
126             *
127             * @return An array of PortletDataHandlerControls
128             * @throws PortletDataException if a portlet data exception occurred
129             */
130            public PortletDataHandlerControl[] getImportControls()
131                    throws PortletDataException;
132    
133            /**
134             * Returns an array of the metadata controls defined for this data handler.
135             * These controls enable the developer to create fine grained controls over
136             * import behavior of metadata such as tags, categories, ratings or
137             * comments. The controls are rendered in the export UI.
138             *
139             * @return an array of PortletDataHandlerControls
140             * @throws PortletDataException if a portlet data exception occurred
141             */
142            public PortletDataHandlerControl[] getImportMetadataControls()
143                    throws PortletDataException;
144    
145            public String getPortletId();
146    
147            /**
148             * Handles any special processing of the data when the portlet is imported
149             * into a new layout. Can optionally return a modified version of
150             * <code>preferences</code> to be saved in the new portlet.
151             *
152             * @param  portletDataContext the context of the data import
153             * @param  portletId the portlet ID of the portlet
154             * @param  portletPreferences the portlet preferences of the portlet
155             * @param  data the string data that was returned by
156             *         <code>exportData()</code>
157             * @return A modified version of portlet preferences that should be saved.
158             *         <code>Null</code> if the portlet preferences were unmodified by
159             *         this data handler.
160             * @throws PortletDataException if a portlet data exception occurred
161             */
162            public PortletPreferences importData(
163                            PortletDataContext portletDataContext, String portletId,
164                            PortletPreferences portletPreferences, String data)
165                    throws PortletDataException;
166    
167            public boolean isDataLocalized();
168    
169            public boolean isDataPortalLevel();
170    
171            public boolean isDataPortletInstanceLevel();
172    
173            public boolean isDataSiteLevel();
174    
175            /**
176             * Returns whether the data exported by this handler should be included by
177             * default when publishing to live. This should only be <code>true</code>
178             * for data that is meant to be managed in an staging environment such as
179             * CMS content, but not for data meant to be input by users such as wiki
180             * pages or message board posts.
181             *
182             * @return <code>true</code> to publish to live by default
183             */
184            public boolean isPublishToLiveByDefault();
185    
186            public boolean isSupportsDataStrategyCopyAsNew();
187    
188            public void prepareManifestSummary(PortletDataContext portletDataContext)
189                    throws PortletDataException;
190    
191            public void prepareManifestSummary(
192                            PortletDataContext portletDataContext,
193                            PortletPreferences portletPreferences)
194                    throws PortletDataException;
195    
196            public PortletPreferences processExportPortletPreferences(
197                            PortletDataContext portletDataContext, String portletId,
198                            PortletPreferences portletPreferences, Element rootElement)
199                    throws PortletDataException;
200    
201            public PortletPreferences processImportPortletPreferences(
202                            PortletDataContext portletDataContext, String portletId,
203                            PortletPreferences portletPreferences)
204                    throws PortletDataException;
205    
206            public void setPortletId(String portletId);
207    
208    }