001 /** 002 * Copyright (c) 2000-2013 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 com.liferay.portal.kernel.xml.Element; 018 import com.liferay.portal.model.Portlet; 019 020 import javax.portlet.PortletPreferences; 021 022 /** 023 * A <code>PortletDataHandler</code> is a special class capable of exporting and 024 * importing portlet specific data to a Liferay Archive file (LAR) when a site's 025 * layouts are exported or imported. <code>PortletDataHandler</code>s are 026 * defined by placing a <code>portlet-data-handler-class</code> element in the 027 * <code>portlet</code> section of the <b>liferay-portlet.xml</b> file. 028 * 029 * @author Raymond Aug?? 030 * @author Joel Kozikowski 031 * @author Bruno Farache 032 */ 033 public interface PortletDataHandler { 034 035 /** 036 * Deletes the data created by the portlet. Can optionally return a modified 037 * version of <code>preferences</code> if it contains reference to data that 038 * does not exist anymore. 039 * 040 * @param portletDataContext the context of the data deletion 041 * @param portletId the portlet ID of the portlet 042 * @param portletPreferences the portlet preferences of the portlet 043 * @return A modified version of portlet preferences that should be saved. 044 * <code>Null</code> if the portlet preferences were unmodified by 045 * this data handler. 046 * @throws PortletDataException if a portlet data exception occurred 047 */ 048 public PortletPreferences deleteData( 049 PortletDataContext portletDataContext, String portletId, 050 PortletPreferences portletPreferences) 051 throws PortletDataException; 052 053 /** 054 * Returns a string of data to be placed in the <portlet-data> section 055 * of the LAR file. This data will be passed as the <code>data</code> 056 * parameter of <code>importData()</code>. 057 * 058 * @param portletDataContext the context of the data export 059 * @param portletId the portlet ID of the portlet 060 * @param portletPreferences the portlet preferences of the portlet 061 * @return A string of data to be placed in the LAR. It may be XML, but not 062 * necessarily. <code>Null</code> should be returned if no portlet 063 * data is to be written out. 064 * @throws PortletDataException if a portlet data exception occurred 065 */ 066 public String exportData( 067 PortletDataContext portletDataContext, String portletId, 068 PortletPreferences portletPreferences) 069 throws PortletDataException; 070 071 public DataLevel getDataLevel(); 072 073 /** 074 * Returns an array of the portlet preferences that reference data. These 075 * preferences should only be updated if the referenced data is imported. 076 * 077 * @return A String array 078 */ 079 public String[] getDataPortletPreferences(); 080 081 public StagedModelType[] getDeletionSystemEventStagedModelTypes(); 082 083 public PortletDataHandlerControl[] getExportConfigurationControls( 084 long companyId, long groupId, Portlet portlet, 085 boolean privateLayout) 086 throws Exception; 087 088 public PortletDataHandlerControl[] getExportConfigurationControls( 089 long companyId, long groupId, Portlet portlet, long plid, 090 boolean privateLayout) 091 throws Exception; 092 093 /** 094 * Returns an array of the controls defined for this data handler. These 095 * controls enable the developer to create fine grained controls over export 096 * behavior. The controls are rendered in the export UI. 097 * 098 * @return an array of PortletDataHandlerControls 099 * @throws PortletDataException if a portlet data exception occurred 100 */ 101 public PortletDataHandlerControl[] getExportControls() 102 throws PortletDataException; 103 104 /** 105 * Returns an array of the metadata controls defined for this data handler. 106 * These controls enable the developer to create fine grained controls over 107 * export behavior of metadata such as tags, categories, ratings or 108 * comments. The controls are rendered in the export UI. 109 * 110 * @return an array of PortletDataHandlerControls 111 * @throws PortletDataException if a portlet data exception occurred 112 */ 113 public PortletDataHandlerControl[] getExportMetadataControls() 114 throws PortletDataException; 115 116 public long getExportModelCount(ManifestSummary manifestSummary); 117 118 public PortletDataHandlerControl[] getImportConfigurationControls( 119 Portlet portlet, ManifestSummary manifestSummary); 120 121 public PortletDataHandlerControl[] getImportConfigurationControls( 122 String[] configurationPortletOptions); 123 124 /** 125 * Returns an array of the controls defined for this data handler. These 126 * controls enable the developer to create fine grained controls over import 127 * behavior. The controls are rendered in the import UI. 128 * 129 * @return An array of PortletDataHandlerControls 130 * @throws PortletDataException if a portlet data exception occurred 131 */ 132 public PortletDataHandlerControl[] getImportControls() 133 throws PortletDataException; 134 135 /** 136 * Returns an array of the metadata controls defined for this data handler. 137 * These controls enable the developer to create fine grained controls over 138 * import behavior of metadata such as tags, categories, ratings or 139 * comments. The controls are rendered in the export UI. 140 * 141 * @return an array of PortletDataHandlerControls 142 * @throws PortletDataException if a portlet data exception occurred 143 */ 144 public PortletDataHandlerControl[] getImportMetadataControls() 145 throws PortletDataException; 146 147 public String getPortletId(); 148 149 /** 150 * Handles any special processing of the data when the portlet is imported 151 * into a new layout. Can optionally return a modified version of 152 * <code>preferences</code> to be saved in the new portlet. 153 * 154 * @param portletDataContext the context of the data import 155 * @param portletId the portlet ID of the portlet 156 * @param portletPreferences the portlet preferences of the portlet 157 * @param data the string data that was returned by 158 * <code>exportData()</code> 159 * @return A modified version of portlet preferences that should be saved. 160 * <code>Null</code> if the portlet preferences were unmodified by 161 * this data handler. 162 * @throws PortletDataException if a portlet data exception occurred 163 */ 164 public PortletPreferences importData( 165 PortletDataContext portletDataContext, String portletId, 166 PortletPreferences portletPreferences, String data) 167 throws PortletDataException; 168 169 public boolean isDataLocalized(); 170 171 public boolean isDataPortalLevel(); 172 173 public boolean isDataPortletInstanceLevel(); 174 175 public boolean isDataSiteLevel(); 176 177 /** 178 * Returns whether the data exported by this handler should be included by 179 * default when publishing to live. This should only be <code>true</code> 180 * for data that is meant to be managed in an staging environment such as 181 * CMS content, but not for data meant to be input by users such as wiki 182 * pages or message board posts. 183 * 184 * @return <code>true</code> to publish to live by default 185 */ 186 public boolean isPublishToLiveByDefault(); 187 188 public boolean isSupportsDataStrategyCopyAsNew(); 189 190 public void prepareManifestSummary(PortletDataContext portletDataContext) 191 throws PortletDataException; 192 193 public void prepareManifestSummary( 194 PortletDataContext portletDataContext, 195 PortletPreferences portletPreferences) 196 throws PortletDataException; 197 198 public PortletPreferences processExportPortletPreferences( 199 PortletDataContext portletDataContext, String portletId, 200 PortletPreferences portletPreferences, Element rootElement) 201 throws PortletDataException; 202 203 public PortletPreferences processImportPortletPreferences( 204 PortletDataContext portletDataContext, String portletId, 205 PortletPreferences portletPreferences) 206 throws PortletDataException; 207 208 public void setPortletId(String portletId); 209 210 }