com.sap.portal.httpconnectivity.transformationservice

Interface ITransformerService

All Superinterfaces:

IService

public interface ITransformerService
extends IService

The interface for the transformation service that enables the transformation of XML to a scheme.
The service can register or unregister transformers, which can be specified by their name, version, type and scheme.
The source for the transformation must be an XML file and the result can be HTMLB, HTML, XML or any other format.
The implementation of the source must inherit from javax.xml.transform.Source. The XML input can be a file, stream, DOM or other customized class. The source classes provided by the JDK are:

• javax.xml.transform.stream.StreamSource
• javax.xml.transform.sax.SAXSource
• javax.xml.transform.dom.DOMSource

HTTPStreamSource, is used for working with URL based XML sources that use the portal cache, proxy settings and PCD attributes to load XML files from the internet. It is highly recommended to work with this class when loading XML files from the internet.
The implementation of the XML result must inherit from javax.xml.transform.result. The result of the transformation is kept in the format specified by the last transformer in the transformation pipe. Result classes provided by the JDK are:

• javax.xml.transform.stream.StreamResult
• javax.xml.transform.sax.SAXResult
• javax.xml.transform.dom.DOMResult

Each transformation is thread safe and synchronized.
The following is a sample transformation, from BUSDOC to HTMLB, that writes the result to the response:

      String fileLocation = getXMLFileLocation();    
      
      IPageContext context = PageContextFactory.createPageContext(request,response);
       
      ITransformerService tService = (ITransformerService)request.getService(ITransformerService.KEY);
 
      try
      {
           // Getting the BUSDOC transformer information according to it's name
           List busdocTrans = tService.getTransformersInformation(TransformerType.BUILT_IN,ITransformerService.BUILT_IN_TRANSFORMERS_KEY,"BUSDOC_TO_XHTMLB",null,null,null);
           
           // Getting XHTMLB transformer information according to the input and output types 
           List xhtmlbTrans = tService.getTransformersInformation(TransformerType.BUILT_IN,null,null,null,"XHTMLB","HTML");
 
           // Building Transformers list
           List trns = new ArrayList(2);
           trns.add(busdocTrans.get(0));
           trns.add(xhtmlbTrans.get(0));
 
           // Building paramters maps array
           Map[] paramsArray = new Map[2];
                  
           // Setting parameters to the RSS transformer
           paramsArray[0] = new Hashtable(1);
           paramsArray[0].put("VisibleRowsCount","5");
                    
           // Setting parameters to the XHTMLB transformer
           paramsArray[1] = new Hashtable(2);
           paramsArray[1].put(ITransformerService.BUILT_IN_TRANSFORMERS_KEY+ ".HTMLBRenderAtEnd",Boolean.TRUE);
           
           // Getting source file
           // Setting source stream                        
           FileInputStream fis = null;
           try
           {
               fis = new FileInputStream(fileLocation);
           }
           catch (FileNotFoundException e)
           {
               // ... 
           }
 
           StreamSource source = new StreamSource(fis);            
 
           // Setting result stream
           StreamResult strm = new StreamResult(response.getWriter());
                       
           // Transforming and writing to the response
           tService.transform(source, trns, paramsArray, context, null, strm);
       }
       catch (TransformationServiceException e)
       {
           // ...
       }
 

Field Summary

static String	BUILT_IN_TRANSFORMERS_FILE A constant that defines the definition file for built-in transformers.
static String	BUILT_IN_TRANSFORMERS_FOLDER A constant that defines the base folder for built-in transformers.
static String	BUILT_IN_TRANSFORMERS_KEY A constant that defines the component name for built-in transformers.
static String	KEY The service key.
static String	RESOURCE_BUNDLE_NAME A constant that defines the name of the default resource.
static String	RESOURCE_BUNDLE_PARAMETER_NAME A constant that defines the name of the transformer parameter for the resource bundles.
static String	TRANSFORMATION_LOG_SUBLOC A constant that defines the sublocation of the log for the transformer service.
static String	TRANSFORMERS_REGISTRY_ROOT_PATH A constant that defines the path for the transformer providers in the portal registry.
static String	TRNSFRMR_SVC_LOC_STR A constant that defines the location of the log for the transformer service.

Method Summary

ITransformerInformation	createTransformerInformation(String componentName, String transformerName, Float transformerVersion, TransformerType transformerType, String fromUri, String toUri, String description) Creates a new instance of ITransformerInformation.
ITransformerInformation	getTransformerInformation(String transformerKey) Gets a single transformer information object according to the specified key.
List	getTransformersInformation(TransformerType transformerType, String componentName, String transformerName, Float transformerVersion, String fromUri, String toUri) Gets a list of transformers that match the specified properties.
void	releaseTransformers(String componentName) Releases transformers for the specified component.
boolean	setTransformer(ITransformerInformation transformerInfo, EPSAXDefaultHandler saxTransformer, boolean overwrite) Registers a SAX transformer that uses the supplied SAX handler.
boolean	setTransformer(ITransformerInformation transformerInfo, Source source, boolean overwrite) Registers an XSL transformer from the XML source that is already loaded.
boolean	setTransformer(ITransformerInformation transformerInfo, String xslUri, boolean overwrite) Registers an XSL transformer by loading the XSL file from the specified location.
void	transform(Source source, List transformers, Map[] paramMap, com.sapportals.htmlb.rendering.IPageContext context, Map objectsMap, Result output) Activates the transformation process using a list of transformers.
void	transform(Source source, String transformerKey, Map paramMap, com.sapportals.htmlb.rendering.IPageContext context, Map objectsMap, Result output) Activates the transformation process using one transformer.

Methods inherited from interface com.sapportals.portal.prt.service.IService

afterInit, configure, destroy, getContext, getKey, init, release

Field Detail

BUILT_IN_TRANSFORMERS_KEY

static final String BUILT_IN_TRANSFORMERS_KEY

A constant that defines the component name for built-in transformers.

See Also:

Constant Field Values

BUILT_IN_TRANSFORMERS_FOLDER

static final String BUILT_IN_TRANSFORMERS_FOLDER

A constant that defines the base folder for built-in transformers.

See Also:

Constant Field Values

BUILT_IN_TRANSFORMERS_FILE

static final String BUILT_IN_TRANSFORMERS_FILE

A constant that defines the definition file for built-in transformers.

See Also:

Constant Field Values

KEY

static final String KEY

The service key.

See Also:

Constant Field Values

TRANSFORMERS_REGISTRY_ROOT_PATH

static final String TRANSFORMERS_REGISTRY_ROOT_PATH

A constant that defines the path for the transformer providers in the portal registry.

See Also:

Constant Field Values

RESOURCE_BUNDLE_PARAMETER_NAME

static final String RESOURCE_BUNDLE_PARAMETER_NAME

A constant that defines the name of the transformer parameter for the resource bundles.

See Also:

Constant Field Values

RESOURCE_BUNDLE_NAME

static final String RESOURCE_BUNDLE_NAME

A constant that defines the name of the default resource.

See Also:

Constant Field Values

TRNSFRMR_SVC_LOC_STR

static final String TRNSFRMR_SVC_LOC_STR

A constant that defines the location of the log for the transformer service.

See Also:

Constant Field Values

TRANSFORMATION_LOG_SUBLOC

static final String TRANSFORMATION_LOG_SUBLOC

A constant that defines the sublocation of the log for the transformer service.

See Also:

Constant Field Values

Method Detail

transform

void transform(Source source,
               List transformers,
               Map[] paramMap,
               com.sapportals.htmlb.rendering.IPageContext context,
               Map objectsMap,
               Result output)
               throws TransformationServiceException

Activates the transformation process using a list of transformers. Each transformer has an associated map of parameters according to the index of the transformer in the transformers list. The transformers are chained to one another in such a way that the output of transformer X is the input of transformer X+1. The source is the source of the first transformer and the result is the result of the last transformer.
Note: The transformer output scheme must match the input scheme of the next transformer.
The transformers list can hold ITransformerInformation objects, transformers keys or a combination of both.
Getting data from an external URL can be done using the HTTPStreamSource object.

Parameters:

source - the source for the transformation

transformers - a list of transformers

paramMap - an array holding the parameters for each transformer

context - the page context

objectsMap - for future use

output - the result of the transformation

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers does not exist or if an error occurs during the transformation

See Also:

ITransformerInformation.getKey()

transform

void transform(Source source,
               String transformerKey,
               Map paramMap,
               com.sapportals.htmlb.rendering.IPageContext context,
               Map objectsMap,
               Result output)
               throws TransformationServiceException

Activates the transformation process using one transformer.

Parameters:

source - the source for the transformation

transformerKey - the key of the transformer

paramMap - the parameters for the transformer

context - the page context

objectsMap - for future use

output - the result of the transformation

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers doesn't exist or if an error occurs during the transformation

setTransformer

boolean setTransformer(ITransformerInformation transformerInfo,
                       String xslUri,
                       boolean overwrite)
                       throws TransformationServiceException

Registers an XSL transformer by loading the XSL file from the specified location.

Parameters:

transformerInfo - the transformer information

xslUri - the URI of the transformer,

overwrite - when true and the transformer already exists, the service replaces the existing transformer with the new one

Returns:

true if the transformer was added to the service, false if it was not added

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers doesn't exist or if an error occurs during the transformation

setTransformer

boolean setTransformer(ITransformerInformation transformerInfo,
                       Source source,
                       boolean overwrite)
                       throws TransformationServiceException

Registers an XSL transformer from the XML source that is already loaded.

Parameters:

transformerInfo - the transformer information

source - the source for the transformation

overwrite - when true and the transformer already exists, the service replaces the current transformer with the new one

Returns:

true if the transformer was added to the service, false if it was not added

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers doesn't exist or if an error occurs during the transformation

setTransformer

boolean setTransformer(ITransformerInformation transformerInfo,
                       EPSAXDefaultHandler saxTransformer,
                       boolean overwrite)
                       throws TransformationServiceException

Registers a SAX transformer that uses the supplied SAX handler.
The following is sample code for registering a new temporary SAX transformer:

      public void init(IPortalComponentInitContext initContext)
          throws PortalComponentException
      {
          mm_initContext = initContext;
           
             //Getting the service
          ITransformerService tService = 
              (ITransformerService) PortalRuntime.getRuntimeResources().getService(ITransformerService.KEY);
 
          // Creating the SAX handlers instance. 
          // TestUIDSSAXHandler derives from EPSAXDefaultHandler.
          TestUIDSSAXHandler hndlr = new TestUIDSSAXHandler();
   
          try
          {                    
                 // Creating the new transformer information
              ITransformerInformation ti = 
                   tService.createTransformerInformation(initContext.getApplicationName()
                               ,"UID_ADDER",new Float(1.0)
                               ,TransformerType.TEMPORARY
                               ,"XML","XML","Temporary SAX unique ID adder");
                               
              // Setting the transformer
          tService.setTransformer(ti,hndlr,false);                       
      }
      catch (TransformationServiceException e)
      {
         //...
      }
      super.init(initContext);
  }
 

Parameters:

transformerInfo - the transformer information

saxTransformer - the SAX handler that is associated with this transformer

overwrite - when true and the transformer already exists, the service replaces the current transformer with the new one

Returns:

true if the transformer was added to the service, false if it was not added

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers doesn't exist or if an error occurs during the transformation

releaseTransformers

void releaseTransformers(String componentName)

Releases transformers for the specified component. Releasing built-in transformers is not possible. It is the responsibility of the provider to release its own transformers.

Parameters:

componentName - the component name

createTransformerInformation

ITransformerInformation createTransformerInformation(String componentName,
                                                     String transformerName,
                                                     Float transformerVersion,
                                                     TransformerType transformerType,
                                                     String fromUri,
                                                     String toUri,
                                                     String description)
                                                     throws TransformationServiceException

Creates a new instance of ITransformerInformation. This method is used mainly when setting new transformers.

Parameters:

componentName - the component name

transformerName - the transformer name

transformerVersion - the transformer version

transformerType - the transformer type

fromUri - the source scheme

toUri - the result scheme

description - the transformer description

Returns:

transformer a transformer information instance

Throws:

TransformationServiceException - if the source data is corrupt, if it cannot write to the result, if one of the transformers doesn't exist or if an error occurs during the transformation

getTransformersInformation

List getTransformersInformation(TransformerType transformerType,
                                String componentName,
                                String transformerName,
                                Float transformerVersion,
                                String fromUri,
                                String toUri)

Gets a list of transformers that match the specified properties. Enables the user to get all transformers by output/input scheme, by type, by component, by version and by name.
The input values are not required. The returned list is not sorted and can be null.

Parameters:

transformerType - the type of the requested transformers

componentName - the component name

transformerName - the transformer name

transformerVersion - the version of the transformer

fromUri - the source scheme

toUri - the result scheme

Returns:

a list of transformers according to the input parameters

getTransformerInformation

ITransformerInformation getTransformerInformation(String transformerKey)

Gets a single transformer information object according to the specified key. Returns null if the object doesn't exist.

Parameters:

transformerKey - the transformer key

Returns:

the requested transformer information object

Access Rights

This class can be accessed from:

SC	DC	Public Part	ACH
[sap.com] EP-ADMIN	[sap.com] tc/ep/admin/api/extd	api	EP-PIN