How to (Java)

Implement an active tag

Please read first "how-to design its own module".

There is a simple contract to follow for implementing an active tag, which must have :

• a method invoked by the engine when unmarshalling,
• a method invoked at runtime.

For this purpose, any active tag must extend org.inria.ns.reflex.processor.core.AbstractAction or one of its subclass. The method for unmarshalling must have the following signature :

public static AbstractAction unmarshal(
  AbstractAction parent, Element element )

This method is invoked automatically by the engine when the corresponding tag is encountered ; it should create an instance of the expected class. If the tag accept attributes, they have to be processed in this method. In a future release, the engine will check automatically with a schema if a tag is valid. After creating an instance of an active tag class, the unmarshal method MUST tell to the engine that the unmarshall process must go on ; in some rare case, developers can block it, but it is not recommended :

  public static AbstractAction unmarshal(
      AbstractAction parent, Element element )
      throws XMLException {
    // create an instance of my active tag
    MyAction myAction = new MyAction( parent, element );
    // unmarshal inside my element
    AbstractAction.unmarshal( myAction, element );
    // return my instance
    return myAction;
  }

If the class extends directly org.inria.ns.reflex.processor.core.AbstractAction, the custom process should start from the method :

public void runAction(DataSet dataSet)

If the class intend to produce a property to put in the data set, it should extend org.inria.ns.reflex.processor.core.AbstractSetAction and simply implements :

public Object getComputedValue(DataSet dataSet)

Use XPath

XPath always appear in expressions in Active Tags, that is to say an XPath expression surrounded by curly braces. The class that handles expressions is org.inria.ns.reflex.xml.xpath.Expression.

XPaths expressions are used when an object reference must be handled by a tag ; for example, when an attribute value appears as an expression, like this :

  <xcl:transform output="{ value( $web:response/@web:output ) }" source="{ $xml }"/>

As this tag requires an #io:output stream to write to, it uses an attribute that contains an expression. In the unmarshal() method of this tag :

  public static AbstractAction unmarshal(
      AbstractAction parent, Element element )
      throws XMLException {
    // create an expression from @output from the current element
    Expression output = Expression.parseValueTemplate(
      element, "output"
    );
    TransformAction transformAction = new TransformAction(
      output, parent, element
    );
    // ...
  }
  public TransformAction(
      Expression output, AbstractAction parent, Element element ) {
    this(parent, element);
    this.output = output;
  }
  private Expression output;

In the runAction() method :

  public void runAction( DataSet dataSet )
        throws ExecutionException {
    Object output = this.output.compute( dataSet.getXPathVariableResolver() );
    // io:output is either an OutputStream or a Writer
    if ( output instanceof OutputStream ) {
      OutputStream os = (OutputStream) output;
      // ...
    } else if ( output instanceof Writer ) {
      Writer w = (Writer) output;
      // ...
    } else {
      // error ?
    }
  }

If a QName must be computed, the class org.inria.ns.reflex.xml.QExpression can be used to unmarshal attribute values.

  <io:file name="myFile" uri="xmldb:provider://user:pwd@host:port/path/to/resource">
    <xcl:param name="xmldb-resource-type" value="XMLResource"/>
  </io:file>

  <xcl:transform output="/path/to/doc.html" source="/path/to/doc.xml"
 stylesheet="/path/to/stylesheet.xsl">
    <xcl:param name="date" value="{ $date }"/>
    <xcl:if test="{ $page }">
      <xcl:then>
        <xcl:param name="page" value="{ $page }"/>
      </xcl:then>
    </xcl:if>
  </xcl:transform>

  SomeComponent myComponent = ...
  // Checking for parameters
  if ( this.actions != null ) {
    AbstractAction.ParameterAdapter adapter =
      new AbstractAction.ParameterAdapter() {
        public void setParameter( Object name, Object value ) {
          if ( myComponent != null ) {
              myComponent.setParameter( name, value );
          }
        }
    }
    // this will set a parameter to the component for each
    // parameter encountered when performing subactions
    adapter.setParameters( dataSet );
  }

  List context = dataSet.pushContext();
  try {
    // subactions will feed the context
    runActions( dataSet );
  } finally {
    dataSet.popContext();
  }
  // use the objects that were stored in the context
  ...

<exp:element name="xcl:parse-html" source="res:org.acme.myTags.tagSoup.ParseHTMLAction"/>