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 <portlet-data> 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 }