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     * <p>
021     * A <code>PortletDataHandler</code> is a special class capable of exporting and
022     * importing portlet specific data to a Liferay Archive file (LAR) when a site's
023     * layouts are exported or imported. <code>PortletDataHandler</code>s are
024     * defined by placing a <code>portlet-data-handler-class</code> element in the
025     * <code>portlet</code> section of the <b>liferay-portlet.xml</b> file.
026     * </p>
027     *
028     * @author Raymond Augé
029     * @author Joel Kozikowski
030     * @author Bruno Farache
031     */
032    public interface PortletDataHandler {
033    
034            /**
035             * Deletes the data created by the portlet. Can optionally return a modified
036             * version of <code>preferences</code> if it contains reference to data that
037             * does not exist anymore.
038             *
039             * @param  portletDataContext the context of the data deletion
040             * @param  portletId the portlet ID of the portlet
041             * @param  portletPreferences the portlet preferences of the portlet
042             * @return A modified version of portlet preferences that should be saved.
043             *         <code>Null</code> if the portlet preferences were unmodified by
044             *         this data handler.
045             */
046            public PortletPreferences deleteData(
047                            PortletDataContext portletDataContext, String portletId,
048                            PortletPreferences portletPreferences)
049                    throws PortletDataException;
050    
051            /**
052             * Returns a string of data to be placed in the &lt;portlet-data&gt; section
053             * of the LAR file. This data will be passed as the <code>data</code>
054             * parameter of <code>importData()</code>.
055             *
056             * @param  portletDataContext the context of the data export
057             * @param  portletId the portlet ID of the portlet
058             * @param  portletPreferences the portlet preferences of the portlet
059             * @return A string of data to be placed in the LAR. It may be XML, but not
060             *         necessarily. <code>Null</code> should be returned if no portlet
061             *         data is to be written out.
062             */
063            public String exportData(
064                            PortletDataContext portletDataContext, String portletId,
065                            PortletPreferences portletPreferences)
066                    throws PortletDataException;
067    
068            /**
069             * Returns an array of the controls defined for this data handler. These
070             * controls enable the developer to create fine grained controls over export
071             * behavior. The controls are rendered in the export UI.
072             *
073             * @return an array of PortletDataHandlerControls
074             */
075            public PortletDataHandlerControl[] getExportControls()
076                    throws PortletDataException;
077    
078            /**
079             * Returns an array of the metadata controls defined for this data handler.
080             * These controls enable the developer to create fine grained controls over
081             * export behavior of metadata such as tags, categories, ratings or
082             * comments. The controls are rendered in the export UI.
083             *
084             * @return an array of PortletDataHandlerControls
085             */
086            public PortletDataHandlerControl[] getExportMetadataControls()
087                    throws PortletDataException;
088    
089            /**
090             * Returns an array of the controls defined for this data handler. These
091             * controls enable the developer to create fine grained controls over import
092             * behavior. The controls are rendered in the import UI.
093             *
094             * @return An array of PortletDataHandlerControls
095             */
096            public PortletDataHandlerControl[] getImportControls()
097                    throws PortletDataException;
098    
099            /**
100             * Returns an array of the metadata controls defined for this data handler.
101             * These controls enable the developer to create fine grained controls over
102             * import behavior of metadata such as tags, categories, ratings or
103             * comments. The controls are rendered in the export UI.
104             *
105             * @return an array of PortletDataHandlerControls
106             */
107            public PortletDataHandlerControl[] getImportMetadataControls()
108                    throws PortletDataException;
109    
110            /**
111             * Handles any special processing of the data when the portlet is imported
112             * into a new layout. Can optionally return a modified version of
113             * <code>preferences</code> to be saved in the new portlet.
114             *
115             * @param  portletDataContext the context of the data import
116             * @param  portletId the portlet ID of the portlet
117             * @param  portletPreferences the portlet preferences of the portlet
118             * @param  data the string data that was returned by
119             *         <code>exportData()</code>
120             * @return A modified version of portlet preferences that should be saved.
121             *         <code>Null</code> if the portlet preferences were unmodified by
122             *         this data handler.
123             */
124            public PortletPreferences importData(
125                            PortletDataContext portletDataContext, String portletId,
126                            PortletPreferences portletPreferences, String data)
127                    throws PortletDataException;
128    
129            /**
130             * Returns <code>true</code> to allow the user to export data for this
131             * portlet even though it may not belong to any pages. See LPS-1624.
132             *
133             * @return <code>true</code> to allow the user to export data for this
134             *         portlet even though it may not belong to any pages
135             */
136            public boolean isAlwaysExportable();
137    
138            public boolean isAlwaysStaged();
139    
140            /**
141             * Returns whether the data exported by this handler should be included by
142             * default when publishing to live. This should only be <code>true</code>
143             * for data that is meant to be managed in an staging environment such as
144             * CMS content, but not for data meant to be input by users such as wiki
145             * pages or message board posts.
146             *
147             * @return <code>true</code> to publish to live by default
148             */
149            public boolean isPublishToLiveByDefault();
150    
151    }