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