001 /** 002 * Copyright (c) 2000-2010 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 023 * community's layouts are exported or imported. 024 * <code>PortletDataHandler</code>s are defined by placing a 025 * <code>portlet-data-handler-class</code> element in the <code>portlet</code> 026 * section of the <b>liferay-portlet.xml</b> file. 027 * </p> 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 context the context of the data deletion 041 * @param portletId the portlet id of the portlet 042 * @param preferences the portlet preferences of the portlet 043 * @return A modified version of preferences that should be saved. 044 * <code>Null</code> if the preferences were unmodified by this data 045 * handler. 046 */ 047 public PortletPreferences deleteData( 048 PortletDataContext context, String portletId, 049 PortletPreferences preferences) 050 throws PortletDataException; 051 052 /** 053 * Returns a string of data to be placed in the <portlet-data> section 054 * of the LAR file. This data will be passed as the <code>data</code> 055 * parameter of <code>importData()</code>. 056 * 057 * @param context the context of the data export 058 * @param portletId the portlet id of the portlet 059 * @param preferences the portlet preferences of the portlet 060 * @return A string of data to be placed in the LAR. It may be XML, but not 061 * necessarily. <code>Null</code> should be returned if no portlet 062 * data is to be written out. 063 */ 064 public String exportData( 065 PortletDataContext context, String portletId, 066 PortletPreferences preferences) 067 throws PortletDataException; 068 069 /** 070 * Returns an array of the controls defined for this data handler. These 071 * controls enable the developer to create fine grained controls over export 072 * behavior. The controls are rendered in the export UI. 073 * 074 * @return an array of PortletDataHandlerControls 075 */ 076 public PortletDataHandlerControl[] getExportControls() 077 throws PortletDataException; 078 079 /** 080 * Returns an array of the controls defined for this data handler. These 081 * controls enable the developer to create fine grained controls over import 082 * behavior. The controls are rendered in the import UI. 083 * 084 * @return An array of PortletDataHandlerControls 085 */ 086 public PortletDataHandlerControl[] getImportControls() 087 throws PortletDataException; 088 089 /** 090 * Handles any special processing of the data when the portlet is imported 091 * into a new layout. Can optionally return a modified version of 092 * <code>preferences</code> to be saved in the new portlet. 093 * 094 * @param context the context of the data import 095 * @param portletId the portlet id of the portlet 096 * @param preferences the portlet preferences of the portlet 097 * @param data the string data that was returned by 098 * <code>exportData()</code> 099 * @return A modified version of preferences that should be saved. 100 * <code>Null</code> if the preferences were unmodified by this data 101 * handler. 102 */ 103 public PortletPreferences importData( 104 PortletDataContext context, String portletId, 105 PortletPreferences preferences, String data) 106 throws PortletDataException; 107 108 /** 109 * Returns <code>true</code> to allow the user to export data for this 110 * portlet even though it may not belong to any pages. See LPS-1624. 111 * 112 * @return <code>true</code> to allow the user to export data for this 113 * portlet even though it may not belong to any pages 114 */ 115 public boolean isAlwaysExportable(); 116 117 /** 118 * Returns whether the data exported by this handler should be included by 119 * default when publishing to live. This should only be <code>true</code> 120 * for data that is meant to be managed in an staging environment such as 121 * CMS content, but not for data meant to be input by users such as wiki 122 * pages or message board posts. 123 * 124 * @return <code>true</code> to publish to live by default 125 */ 126 public boolean isPublishToLiveByDefault(); 127 128 }