com.sap.portal.httpconnectivity.transformationservice

Interface ITransformerService

All Superinterfaces:

IService

public interface ITransformerService

extends IService

Service that is responsible for transforming XMLs to various schemes using transformers. Users can add and remove transformers as they wish.
Transformers can be found according to their name, version, type and schemes definition.
The source of the transformation process must be an XML file and the result can be HTMLB, HTML, Other XML or any format depending on the transformers.
Each transformation is thread safe and synchronized.
Usage example that transform BUSDOC to HTMLB and write 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 Built-in transformers definition file
static String	BUILT_IN_TRANSFORMERS_FOLDER Base folder of the built-in transformers
static String	BUILT_IN_TRANSFORMERS_KEY The component name for the built-in transformers
static String	KEY Service key
static String	RESOURCE_BUNDLE_NAME Name of the default resource
static String	RESOURCE_BUNDLE_PARAMETER_NAME Name of the transformer parameter of resource bundles
static String	TRANSFORMATION_LOG_SUBLOC Sub location of the log for the transformer service
static String	TRANSFORMERS_REGISTRY_ROOT_PATH The path of the transformer providers in the registry
static String	TRNSFRMR_SVC_LOC_STR 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 new instance of ITransformerInformation.
ITransformerInformation	getTransformerInformation(String transformerKey) Gets a single transformer information according to it's key.
List	getTransformersInformation(TransformerType transformerType, String componentName, String transformerName, Float transformerVersion, String fromUri, String toUri) Gets a list of transformers that match all filter properties.
void	releaseTransformers(String componentName) Releases transformers of a specific component.
boolean	setTransformer(ITransformerInformation transformerInfo, EPSAXDefaultHandler saxTransformer, boolean overwrite) Sets a SAX transformer that will use the supplied SAX handler.
boolean	setTransformer(ITransformerInformation transformerInfo, Source source, boolean overwrite) Set an XSL transformer from XML source that was already loaded.
boolean	setTransformer(ITransformerInformation transformerInfo, String xslUri, boolean overwrite) Set an XSL transformer by loading XSL file from location specified in the URI parameter.
void	transform(Source source, List transformers, Map[] paramMap, IPageContext context, Map objectsMap, Result output) Activates the transformation process over a list of transformers.
void	transform(Source source, String transformerKey, Map paramMap, IPageContext context, Map objectsMap, Result output) Activates transformation process on 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

public static final String BUILT_IN_TRANSFORMERS_KEY

The component name for the built-in transformers

See Also:

Constant Field Values

BUILT_IN_TRANSFORMERS_FOLDER

public static final String BUILT_IN_TRANSFORMERS_FOLDER

Base folder of the built-in transformers

See Also:

Constant Field Values

BUILT_IN_TRANSFORMERS_FILE

public static final String BUILT_IN_TRANSFORMERS_FILE

Built-in transformers definition file

See Also:

Constant Field Values

KEY

public static final String KEY

Service key

See Also:

Constant Field Values

TRANSFORMERS_REGISTRY_ROOT_PATH

public static final String TRANSFORMERS_REGISTRY_ROOT_PATH

The path of the transformer providers in the registry

See Also:

Constant Field Values

RESOURCE_BUNDLE_PARAMETER_NAME

public static final String RESOURCE_BUNDLE_PARAMETER_NAME

Name of the transformer parameter of resource bundles

See Also:

Constant Field Values

RESOURCE_BUNDLE_NAME

public static final String RESOURCE_BUNDLE_NAME

Name of the default resource

See Also:

Constant Field Values

TRNSFRMR_SVC_LOC_STR

public static final String TRNSFRMR_SVC_LOC_STR

Location of the log for the transformer service

TRANSFORMATION_LOG_SUBLOC

public static final String TRANSFORMATION_LOG_SUBLOC

Sub location of the log for the transformer service

See Also:

Constant Field Values

Method Detail

transform

public void transform(Source source,
                      List transformers,
                      Map[] paramMap,
                      IPageContext context,
                      Map objectsMap,
                      Result output)
               throws TransformationServiceException

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

Parameters:

source - source for the transformation. Can be instances of SAXSource, StreamSource, DOMSource or and derived class from the previous classes

transformers - List of transformers information or transformers keys

paramMap - array holding the parameters for each transformer

context - the page context

objectsMap - future usage

output - the output of the transformation. Can be instance of StreamResult,DOMResult or SAXResult.

Throws:

TransformationServiceException - when source data is corrupted, when cannot write to the result, when one of the transformers doesn't exists and when error occures during the transformation

See Also:

ITransformerInformation.getKey()

transform

public void transform(Source source,
                      String transformerKey,
                      Map paramMap,
                      IPageContext context,
                      Map objectsMap,
                      Result output)
               throws TransformationServiceException

Activates transformation process on one transformer.

Parameters:

source - source for the transformation. Can be instances of SAXSource, StreamSource or DOMSource.

transformerKey - The key of the transformer

paramMap - parameters for the transformer

context - the page context

objectsMap - future usage

output - the output of the transformation. Can be instance of StreamResult,DOMResult or SAXResult.

Throws:

TransformationServiceException - when source data is corrupted, when cannot write to the result, when one of the transformers doesn't exists and when error occures during the transformation

setTransformer

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

Set an XSL transformer by loading XSL file from location specified in the URI parameter.

Parameters:

transformerInfo - the transformer information

xslUri - the URI of the transformer. It can be a URL or location on the file system.

overwrite - when true and the transformer already exists the service will replace the current transformer with the new one

Returns:

true when the transformer was added to the service, false when not (usually because it already exists)

Throws:

TransformationServiceException - when the transformer cannot be built because of the file was not found, the XSL is not valid or other general problems

setTransformer

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

Set an XSL transformer from XML source that was already loaded.

Parameters:

transformerInfo - the transformer information

source - DOMSource or StreamSource holding the data of the XSL

overwrite - when true and the transformer already exists the service will replace the current transformer with the new one

Returns:

true when the transformer was added to the service, false when not (usually because it already exists)

Throws:

TransformationServiceException - when the transformer cannot be built because the XSL is not valid or other general problems

setTransformer

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

Sets a SAX transformer that will use the supplied SAX handler.

Usage example of setting 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 assossiated with this transformer

overwrite - when true and the transformer already exists the service will replace the current transformer with the new one

Returns:

true when the transformer was added to the service, false when not (usually because it already exists)

Throws:

TransformationServiceException - when the handler is a null pointer or it cannot be cloned

releaseTransformers

public void releaseTransformers(String componentName)

Releases transformers of a specific component. Releasing built-in transformers is impossible. It is the resposibility of the transformers provider to release it's own transformers.

Parameters:

componentName - the protal component name

createTransformerInformation

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

Creates new instance of ITransformerInformation. Used mainly when setting new transformers.

Parameters:

componentName - the component name

transformerName - the transformer name

transformerVersion - the version of the transformer

transformerType - type of transformer

fromUri - source scheme

toUri - result scheme

description - transformer description

Returns:

transformer information instance

Throws:

TransformationServiceException - when input data is missing

getTransformersInformation

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

Gets a list of transformers that match all filter properties. Using this method enables the user to get all transformers by output/input scheme, by type, by component, by version and by name. No input value is mandatory. The retuned list might be empty. The returned list is not sorted and might be empty.

Parameters:

transformerType - the type of the requested transformers

componentName - the component name

transformerName - the name

transformerVersion - the version

fromUri - source scheme URI

toUri - result scheme URI

Returns:

list of ITransformerInformation objects mathcing the input parameters

getTransformerInformation

public ITransformerInformation getTransformerInformation(String transformerKey)

Gets a single transformer information according to it's key.

Parameters:

transformerKey - the transformer key

Returns:

the requested transformer information. If non exists the return value is null