com.appiancorp.suiteapi.ix.data.portlet

Class PortletIxHelper

java.lang.Object

com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper

Direct Known Subclasses:

DefaultPortletIxHelper

public abstract class PortletIxHelper
extends java.lang.Object

This is the base class for all portlet import/export (ix) helper classes. A "portlet ix helper class" is a concrete class that extends this class. A different portlet ix helper class can be specified for each PortletType, using the optional portlet type extension PortletType.EXTENSION_PORTLET_IX_HELPER_CLASS. The ix helper class can be registered along with the portlet type definition in portlet-type-config.xml (see that file for examples of this).

It is not required to implement a custom helper class for every portlet type. If a portlet type does not specify an ix helper class, portlets of that type will still be exported & imported correctly, but the portlet parameters will NOT be exported/imported. Not importing the parameters will result in the portlet being un-configured after it is imported in the target system (unless the portlet has no configuration in the first place or has a fallback configuration, such as the My Tasks portlet).

In order to enable the export & import of portlet parameters, there are 2 options:

1. If the portlet has parameters, but none of them reference Appian objects, no custom helper class needs to be implemented. Instead, the default helper DefaultPortletIxHelper should be specified as the ix helper for that portlet type; this is all that's needed for the portlet parameters to be exported & imported.
2. If the portlet has some parameters that reference Appian objects, a custom ix helper must be implemented to enable the import & export of the parameters. The custom helper needs to implement these two methods: replaceIdsWithUuids(java.util.Map<java.lang.String, java.lang.Object>, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ExportBinder) and replaceUuidsWithIds(java.util.Map<java.lang.String, java.lang.Object>, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ImportBinder).

Additionally, a custom portlet ix helper class can be implemented in order to export & import custom portlet data (data that is not stored within the portlet parameters map). In that case, the custom helper needs to implement these methods: exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext)/exportResources(java.lang.Long, com.appiancorp.services.ServiceContext, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ResourceExporter) and importExtraDataAndResources(java.lang.Long, java.util.Map<java.lang.String, java.lang.String>, com.appiancorp.services.ServiceContext, com.appiancorp.suiteapi.ix.data.portlet.PortletIxHelper.ResourceImporter). This can be used to enable import/export of binary files and [String, String] key-value pairs.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PortletIxHelper.ExportBinder Allows mapping local ids to UUIDs.
static class	PortletIxHelper.ImportBinder Allows mapping UUIDs to local ids.
static class	PortletIxHelper.ResourceExporter
static class	PortletIxHelper.ResourceImporter

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	PortletIxHelper()

Method Summary

Modifier and Type	Method and Description
protected void	addDiagnosticMessage(com.appiancorp.ix.diagnostics.Diagnostic d) Adds a message (such as a warning) that will be displayed to the user after the overall export or import operation is complete.
java.util.Map<java.lang.String,java.lang.String>	exportExtraData(java.lang.Long portletId, ServiceContext sc) Retrieves any custom portlet data to be exported.
void	exportResources(java.lang.Long portletId, ServiceContext sc, PortletIxHelper.ResourceExporter re) Exports portlet resources (such as binary files).
static PortletIxHelper	getInstance(java.lang.Class<? extends PortletIxHelper> portletIxHelperClass, com.appiancorp.ix.Operation op, java.lang.Long portletId, java.lang.String portletUuid, com.appiancorp.ix.diagnostics.Diagnostics d) Deprecated. use getInstance(Class, Operation, Long, String, Diagnostics, ServiceContext)
static PortletIxHelper	getInstance(java.lang.Class<? extends PortletIxHelper> portletIxHelperClass, com.appiancorp.ix.Operation op, java.lang.Long portletId, java.lang.String portletUuid, com.appiancorp.ix.diagnostics.Diagnostics d, ServiceContext sc)
protected ServiceContext	getServiceContext() Returns the current service context.
protected com.appiancorp.ix.TypedId<com.appiancorp.ix.data.PortletHaul,java.lang.Long,java.lang.String>	getTypedId() Returns the id of the portlet that this helper is processing.
void	importExtraDataAndResources(java.lang.Long portletId, java.util.Map<java.lang.String,java.lang.String> extraData, ServiceContext sc, PortletIxHelper.ResourceImporter ri) Stores any custom portlet data exported using exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext) and exportResources(Long, ServiceContext, ResourceExporter).
abstract void	replaceIdsWithUuids(java.util.Map<java.lang.String,java.lang.Object> portletParamsMap, PortletIxHelper.ExportBinder b) Replaces all local ids within the portlet parameters with UUIDs.
abstract void	replaceUuidsWithIds(java.util.Map<java.lang.String,java.lang.Object> portletParamsMap, PortletIxHelper.ImportBinder b) Replaces all UUIDs within the portlet parameters with local ids.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PortletIxHelper

protected PortletIxHelper()

Method Detail

getInstance

@Deprecated
public static PortletIxHelper getInstance(java.lang.Class<? extends PortletIxHelper> portletIxHelperClass,
                                                      com.appiancorp.ix.Operation op,
                                                      java.lang.Long portletId,
                                                      java.lang.String portletUuid,
                                                      com.appiancorp.ix.diagnostics.Diagnostics d)

Deprecated. use getInstance(Class, Operation, Long, String, Diagnostics, ServiceContext)

getInstance

public static PortletIxHelper getInstance(java.lang.Class<? extends PortletIxHelper> portletIxHelperClass,
                                          com.appiancorp.ix.Operation op,
                                          java.lang.Long portletId,
                                          java.lang.String portletUuid,
                                          com.appiancorp.ix.diagnostics.Diagnostics d,
                                          ServiceContext sc)

getServiceContext

protected ServiceContext getServiceContext()

Returns the current service context.

getTypedId

protected com.appiancorp.ix.TypedId<com.appiancorp.ix.data.PortletHaul,java.lang.Long,java.lang.String> getTypedId()

Returns the id of the portlet that this helper is processing.

addDiagnosticMessage

protected void addDiagnosticMessage(com.appiancorp.ix.diagnostics.Diagnostic d)

Adds a message (such as a warning) that will be displayed to the user after the overall export or import operation is complete.

replaceIdsWithUuids

public abstract void replaceIdsWithUuids(java.util.Map<java.lang.String,java.lang.Object> portletParamsMap,
                                         PortletIxHelper.ExportBinder b)
                                  throws AppianException

Replaces all local ids within the portlet parameters with UUIDs. This method is invoked during the export of a portlet. The UUID bound to each local id should be retrieved using the provided PortletIxHelper.ExportBinder.

Parameters:

portletParamsMap - The map of portlet parameters (see Portlet.getParameters()).

b - API for mapping local ids to uuids.

Throws:

AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

replaceUuidsWithIds

public abstract void replaceUuidsWithIds(java.util.Map<java.lang.String,java.lang.Object> portletParamsMap,
                                         PortletIxHelper.ImportBinder b)
                                  throws AppianException

Replaces all UUIDs within the portlet parameters with local ids. This method is invoked during the import of a portlet, and performs the reverse of the conversions made by replaceIdsWithUuids(Map, ExportBinder). The local id corresponding to each UUID should be retrieved using the provided PortletIxHelper.ImportBinder.

Parameters:

portletParamsMap - The map of portlet parameters (see Portlet.getParameters()).

b - API for mapping uuids to local ids.

Throws:

AppianException - If the import of this portlet should be failed (the import driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the import of other objects).

exportExtraData

public java.util.Map<java.lang.String,java.lang.String> exportExtraData(java.lang.Long portletId,
                                                                        ServiceContext sc)
                                                                 throws AppianException

Retrieves any custom portlet data to be exported.

Parameters:

portletId - The id of the portlet being exported.

sc - The service context of the user performing the export.

Returns:

A map of additional data to be exported. This data will be passed in to #importExtraData during import of the portlet.

Throws:

AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

exportResources

public void exportResources(java.lang.Long portletId,
                            ServiceContext sc,
                            PortletIxHelper.ResourceExporter re)
                     throws AppianException

Exports portlet resources (such as binary files).

Parameters:

portletId - The id of the portlet being exported.

sc - The service context of the user performing the export.

re - API for exporting resources.

Throws:

AppianException - If the export of this portlet should be failed (the export driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the export of other objects).

importExtraDataAndResources

public void importExtraDataAndResources(java.lang.Long portletId,
                                        java.util.Map<java.lang.String,java.lang.String> extraData,
                                        ServiceContext sc,
                                        PortletIxHelper.ResourceImporter ri)
                                 throws AppianException

Stores any custom portlet data exported using exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext) and exportResources(Long, ServiceContext, ResourceExporter).

Parameters:

portletId - The id of the portlet being imported.

extraData - The map data exported using exportExtraData(java.lang.Long, com.appiancorp.services.ServiceContext).

sc - The service context of the user performing the import.

ri - API for importing resources.

Throws:

AppianException - If the import of this portlet should be failed (the import driver will automatically handle the exception: it will add the portlet to the failed list and proceed with the import of other objects).