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 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 <portlet-data> 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 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 */ 083 public PortletDataHandlerControl[] getExportControls() 084 throws PortletDataException; 085 086 /** 087 * Returns an array of the metadata controls defined for this data handler. 088 * These controls enable the developer to create fine grained controls over 089 * export behavior of metadata such as tags, categories, ratings or 090 * comments. The controls are rendered in the export UI. 091 * 092 * @return an array of PortletDataHandlerControls 093 */ 094 public PortletDataHandlerControl[] getExportMetadataControls() 095 throws PortletDataException; 096 097 /** 098 * Returns an array of the controls defined for this data handler. These 099 * controls enable the developer to create fine grained controls over import 100 * behavior. The controls are rendered in the import UI. 101 * 102 * @return An array of PortletDataHandlerControls 103 */ 104 public PortletDataHandlerControl[] getImportControls() 105 throws PortletDataException; 106 107 /** 108 * Returns an array of the metadata controls defined for this data handler. 109 * These controls enable the developer to create fine grained controls over 110 * import behavior of metadata such as tags, categories, ratings or 111 * comments. The controls are rendered in the export UI. 112 * 113 * @return an array of PortletDataHandlerControls 114 */ 115 public PortletDataHandlerControl[] getImportMetadataControls() 116 throws PortletDataException; 117 118 /** 119 * Handles any special processing of the data when the portlet is imported 120 * into a new layout. Can optionally return a modified version of 121 * <code>preferences</code> to be saved in the new portlet. 122 * 123 * @param portletDataContext the context of the data import 124 * @param portletId the portlet ID of the portlet 125 * @param portletPreferences the portlet preferences of the portlet 126 * @param data the string data that was returned by 127 * <code>exportData()</code> 128 * @return A modified version of portlet preferences that should be saved. 129 * <code>Null</code> if the portlet preferences were unmodified by 130 * this data handler. 131 */ 132 public PortletPreferences importData( 133 PortletDataContext portletDataContext, String portletId, 134 PortletPreferences portletPreferences, String data) 135 throws PortletDataException; 136 137 /** 138 * Returns <code>true</code> to allow the user to export data for this 139 * portlet even though it may not belong to any pages. See LPS-1624. 140 * 141 * @return <code>true</code> to allow the user to export data for this 142 * portlet even though it may not belong to any pages 143 */ 144 public boolean isAlwaysExportable(); 145 146 public boolean isAlwaysStaged(); 147 148 public boolean isDataLocalized(); 149 150 /** 151 * Returns whether the data exported by this handler should be included by 152 * default when publishing to live. This should only be <code>true</code> 153 * for data that is meant to be managed in an staging environment such as 154 * CMS content, but not for data meant to be input by users such as wiki 155 * pages or message board posts. 156 * 157 * @return <code>true</code> to publish to live by default 158 */ 159 public boolean isPublishToLiveByDefault(); 160 161 }