PortletDataHandler.java |
1 /** 2 * Copyright (c) 2000-2008 Liferay, Inc. All rights reserved. 3 * 4 * Permission is hereby granted, free of charge, to any person obtaining a copy 5 * of this software and associated documentation files (the "Software"), to deal 6 * in the Software without restriction, including without limitation the rights 7 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 8 * copies of the Software, and to permit persons to whom the Software is 9 * furnished to do so, subject to the following conditions: 10 * 11 * The above copyright notice and this permission notice shall be included in 12 * all copies or substantial portions of the Software. 13 * 14 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 17 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 19 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 20 * SOFTWARE. 21 */ 22 23 package com.liferay.portal.kernel.lar; 24 25 import javax.portlet.PortletPreferences; 26 27 /** 28 * <a href="PortletDataHandler.java.html"><b><i>View Source</i></b></a> 29 * 30 * <p> 31 * A <code>PortletDataHandler</code> is a special class capable of exporting and 32 * importing portlet specific data to a Liferay Archive file (LAR) when a 33 * community's layouts are exported or imported. 34 * <code>PortletDataHandler</code>s are defined by placing a 35 * <code>portlet-data-handler-class</code> element in the <code>portlet</code> 36 * section of the <b>liferay-portlet.xml</b> file. 37 * </p> 38 * 39 * @author Raymond Aug� 40 * @author Joel Kozikowski 41 * @author Bruno Farache 42 * 43 */ 44 public interface PortletDataHandler { 45 46 /** 47 * Deletes the data created by the portlet. Can optionally return a modified 48 * version of <code>prefs</code> if it contains reference to data that 49 * does not exist anymore. 50 * 51 * @param context the context of the data deletion 52 * @param portletId the portlet id of the portlet 53 * @param prefs the portlet preferences of the portlet 54 * 55 * @return A modified version of prefs that should be saved. Null if 56 * the preferences were unmodified by this data handler. 57 * @throws PortletDataException 58 */ 59 public PortletPreferences deleteData( 60 PortletDataContext context, String portletId, 61 PortletPreferences prefs) 62 throws PortletDataException; 63 64 /** 65 * Returns a string of data to be placed in the <portlet-data> section 66 * of the LAR file. This data will be passed as the <code>data</code> 67 * parameter of <code>importData()</code>. 68 * 69 * @param context the context of the data export 70 * @param portletId the portlet id of the portlet 71 * @param prefs the portlet preferences of the portlet 72 * @return A string of data to be placed in the LAR. It may be XML, 73 * but not necessarily. Null should be returned if no portlet 74 * data is to be written out. 75 * @throws PortletDataException 76 */ 77 public String exportData( 78 PortletDataContext context, String portletId, 79 PortletPreferences prefs) 80 throws PortletDataException; 81 82 /** 83 * Returns an array of the controls defined for this data handler. These 84 * controls enable the developer to create fine grained controls over export 85 * behavior. The controls are rendered in the export UI. 86 * 87 * @return an array of PortletDataHandlerControls 88 */ 89 public PortletDataHandlerControl[] getExportControls() 90 throws PortletDataException; 91 92 /** 93 * Returns an array of the controls defined for this data handler. These 94 * controls enable the developer to create fine grained controls over import 95 * behavior. The controls are rendered in the import UI. 96 * 97 * @return An array of PortletDataHandlerControls 98 */ 99 public PortletDataHandlerControl[] getImportControls() 100 throws PortletDataException; 101 102 /** 103 * Handles any special processing of the data when the portlet is imported 104 * into a new layout. Can optionally return a modified version of 105 * <code>prefs</code> to be saved in the new portlet. 106 * 107 * @param context the context of the data import 108 * @param portletId the portlet id of the portlet 109 * @param prefs the portlet preferences of the portlet 110 * @param data the string data that was returned by 111 * <code>exportData()</code> 112 * @return A modified version of prefs that should be 113 * saved. Null if the preferences were unmodified by this data 114 * handler. 115 * @throws PortletDataException 116 */ 117 public PortletPreferences importData( 118 PortletDataContext context, String portletId, 119 PortletPreferences prefs, String data) 120 throws PortletDataException; 121 122 /** 123 * Returns whether the data exported by this handler should be included 124 * by default when publishing to live. This should only be true for data 125 * that is meant to be managed in an staging environment such as CMS 126 * content, but not for data meant to be input by users such as wiki pages 127 * or message board posts. 128 * 129 * @return true to publish to live by default 130 */ 131 public boolean isPublishToLiveByDefault(); 132 133 }