001    /**
002     * Copyright (c) 2000-present 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.portlet.exportimport.lar;
016    
017    import com.liferay.portal.model.Portlet;
018    
019    import javax.portlet.PortletPreferences;
020    
021    /**
022     * A <code>PortletDataHandler</code> is a special class capable of exporting and
023     * importing portlet specific data to a Liferay Archive file (LAR) when a site's
024     * layouts are exported or imported. <code>PortletDataHandler</code>s are
025     * defined by placing a <code>portlet-data-handler-class</code> element in the
026     * <code>portlet</code> section of the <b>liferay-portlet.xml</b> file.
027     *
028     * @author Raymond Aug??
029     * @author Joel Kozikowski
030     * @author Bruno Farache
031     */
032    public interface PortletDataHandler {
033    
034            /**
035             * Returns the portlet's preferences with default data added.
036             *
037             * @param  portletDataContext the context of the data addition
038             * @param  portletId the portlet ID of the portlet
039             * @param  portletPreferences the portlet preferences of the portlet
040             * @return a modified version of the portlet preferences that should be
041             *         saved, or <code>null</code> if the data handler made no changes
042             *         to the portlet preferences
043             * @throws PortletDataException if a portlet data exception occurred
044             */
045            public PortletPreferences addDefaultData(
046                            PortletDataContext portletDataContext, String portletId,
047                            PortletPreferences portletPreferences)
048                    throws PortletDataException;
049    
050            /**
051             * Deletes the data created by the portlet. It can optionally return a
052             * modified version of the portlet preferences if it contains references to
053             * data that no longer exists.
054             *
055             * @param  portletDataContext the context of the data deletion
056             * @param  portletId the portlet ID of the portlet
057             * @param  portletPreferences the portlet preferences of the portlet
058             * @return a modified version of the portlet preferences that should be
059             *         saved, or <code>null</code> if the data handler made no changes
060             *         to the portlet preferences
061             * @throws PortletDataException if a portlet data exception occurred
062             */
063            public PortletPreferences deleteData(
064                            PortletDataContext portletDataContext, String portletId,
065                            PortletPreferences portletPreferences)
066                    throws PortletDataException;
067    
068            /**
069             * Returns a string of data to be placed in the &lt;portlet-data&gt; section
070             * of the LAR file. This data will be passed as the <code>data</code>
071             * parameter of <code>importData()</code>.
072             *
073             * @param  portletDataContext the context of the data export
074             * @param  portletId the portlet ID of the portlet
075             * @param  portletPreferences the portlet preferences of the portlet
076             * @return a string of data to be placed in the LAR, which can be, but not
077             *         limited to XML, or <code>null</code> if no portlet data is to be
078             *         written out
079             * @throws PortletDataException if a portlet data exception occurred
080             */
081            public String exportData(
082                            PortletDataContext portletDataContext, String portletId,
083                            PortletPreferences portletPreferences)
084                    throws PortletDataException;
085    
086            public DataLevel getDataLevel();
087    
088            /**
089             * Returns an array of the portlet preferences that reference data. These
090             * preferences should only be updated if the referenced data is imported.
091             *
092             * @return an array of the portlet preferences that reference data
093             */
094            public String[] getDataPortletPreferences();
095    
096            public StagedModelType[] getDeletionSystemEventStagedModelTypes();
097    
098            public PortletDataHandlerControl[] getExportConfigurationControls(
099                            long companyId, long groupId, Portlet portlet,
100                            boolean privateLayout)
101                    throws Exception;
102    
103            public PortletDataHandlerControl[] getExportConfigurationControls(
104                            long companyId, long groupId, Portlet portlet, long plid,
105                            boolean privateLayout)
106                    throws Exception;
107    
108            /**
109             * Returns an array of the controls defined for this data handler. These
110             * controls enable the developer to create fine grained controls over export
111             * behavior. The controls are rendered in the export UI.
112             *
113             * @return an array of the controls defined for this data handler
114             * @throws PortletDataException if a portlet data exception occurred
115             */
116            public PortletDataHandlerControl[] getExportControls()
117                    throws PortletDataException;
118    
119            /**
120             * Returns an array of the metadata controls defined for this data handler.
121             * These controls enable the developer to create fine grained controls over
122             * export behavior of metadata such as tags, categories, ratings or
123             * comments. The controls are rendered in the export UI.
124             *
125             * @return an array of the metadata controls defined for this data handler
126             * @throws PortletDataException if a portlet data exception occurred
127             */
128            public PortletDataHandlerControl[] getExportMetadataControls()
129                    throws PortletDataException;
130    
131            /**
132             * Returns the number of entities defined for this data handler that are
133             * available for export according to the provided manifest summary, or
134             * <code>-1</code> if no entities are included in the manifest summary.
135             *
136             * @param  manifestSummary the manifest summary listing the number of
137             *         exportable entities
138             * @return the number of entities that are available for export according to
139             *         the manifest summary, or <code>-1</code> if no entities are
140             *         included in the manifest summary
141             */
142            public long getExportModelCount(ManifestSummary manifestSummary);
143    
144            public PortletDataHandlerControl[] getImportConfigurationControls(
145                    Portlet portlet, ManifestSummary manifestSummary);
146    
147            public PortletDataHandlerControl[] getImportConfigurationControls(
148                    String[] configurationPortletOptions);
149    
150            /**
151             * Returns an array of the controls defined for this data handler. These
152             * controls enable the developer to create fine grained controls over import
153             * behavior. The controls are rendered in the import UI.
154             *
155             * @return an array of the controls defined for this data handler
156             * @throws PortletDataException if a portlet data exception occurred
157             */
158            public PortletDataHandlerControl[] getImportControls()
159                    throws PortletDataException;
160    
161            /**
162             * Returns an array of the metadata controls defined for this data handler.
163             * These controls enable the developer to create fine grained controls over
164             * import behavior of metadata such as tags, categories, ratings or
165             * comments. The controls are rendered in the export UI.
166             *
167             * @return an array of the metadata controls defined for this data handler
168             * @throws PortletDataException if a portlet data exception occurred
169             */
170            public PortletDataHandlerControl[] getImportMetadataControls()
171                    throws PortletDataException;
172    
173            public String getPortletId();
174    
175            public int getRank();
176    
177            public String getSchemaVersion();
178    
179            public String getServiceName();
180    
181            /**
182             * Handles any special processing of the data when the portlet is imported
183             * into a new layout. Can optionally return a modified version of
184             * <code>preferences</code> to be saved in the new portlet.
185             *
186             * @param  portletDataContext the context of the data import
187             * @param  portletId the portlet ID of the portlet
188             * @param  portletPreferences the portlet preferences of the portlet
189             * @param  data the string data that was returned by
190             *         <code>exportData()</code>
191             * @return a modified version of the portlet preferences that should be
192             *         saved, or <code>null</code> if the data handler made no changes
193             *         to the portlet preferences
194             * @throws PortletDataException if a portlet data exception occurred
195             */
196            public PortletPreferences importData(
197                            PortletDataContext portletDataContext, String portletId,
198                            PortletPreferences portletPreferences, String data)
199                    throws PortletDataException;
200    
201            public boolean isDataAlwaysStaged();
202    
203            public boolean isDataLocalized();
204    
205            public boolean isDataPortalLevel();
206    
207            public boolean isDataPortletInstanceLevel();
208    
209            public boolean isDataSiteLevel();
210    
211            public boolean isDisplayPortlet();
212    
213            /**
214             * Returns whether the data exported by this handler should be included by
215             * default when publishing to live. This should only be <code>true</code>
216             * for data that is meant to be managed in an staging environment such as
217             * CMS content, but not for data meant to be input by users such as wiki
218             * pages or message board posts.
219             *
220             * @return <code>true</code> if the data exported by this handler should be
221             *         included by default when publishing to live; <code>false</code>
222             *         otherwise
223             */
224            public boolean isPublishToLiveByDefault();
225    
226            /**
227             * Returns <code>true</code> if the data handler stops operations and rolls
228             * back their transactions on operations throwing exceptions.
229             *
230             * @return <code>true</code> if the data handler stops operations and rolls
231             *         back their transactions on operations throwing exceptions;
232             *         <code>false</code> otherwise
233             */
234            public boolean isRollbackOnException();
235    
236            public boolean isSupportsDataStrategyCopyAsNew();
237    
238            public void prepareManifestSummary(PortletDataContext portletDataContext)
239                    throws PortletDataException;
240    
241            public void prepareManifestSummary(
242                            PortletDataContext portletDataContext,
243                            PortletPreferences portletPreferences)
244                    throws PortletDataException;
245    
246            public PortletPreferences processExportPortletPreferences(
247                            PortletDataContext portletDataContext, String portletId,
248                            PortletPreferences portletPreferences)
249                    throws PortletDataException;
250    
251            public PortletPreferences processImportPortletPreferences(
252                            PortletDataContext portletDataContext, String portletId,
253                            PortletPreferences portletPreferences)
254                    throws PortletDataException;
255    
256            public void setPortletId(String portletId);
257    
258            public void setRank(int rank);
259    
260            public boolean validateSchemaVersion(String schemaVersion);
261    
262    }