herwinvw edited this page Sep 13, 2015 · 20 revisions

About OpenBMLParser

OpenBMLParser is a Java implementation of an XML parser for the Behavior Markup Language(BML). Since parsing BML and obtaining constraints between sync points in behaviors specified in BML is a non-trivial endeavor, it is useful to have such a standard implementation. OpenBMLParser is currently used as the BML parser in the AsapRealizer BML realizer.

Obtaining binaries

The latest jar files for OpenBMLParser can be found at http://itchy.techfak.uni-bielefeld.de/ivyrepos/hmirepo/external/java/saiba/ The openbmlparser directory contains the library itself, openbmlparser-test contains a jar file with test utilities that can be employed in junit tests of ones own BML behaviors or extensions, openbmlparser-testresource contains a set of test BML scripts.

Compiling and building

OpenBMLParser is compiled and built using apache ant. Use

ant compile

to compile;

ant dist

to generate the jar files for OpenBMLParser from source. The jar files are placed in the dist directory. Other useful ant targets are doc: generate the javadoc (in the docs directory) junitreport: run the testcases and generate a test report (in test/report)

Javadoc

OpenBMLParser Javadoc

OpenBMLParser test Javadoc

Parsing BML

BMLParser parser = new BMLParser();
BehaviourBlock bb = new BehaviourBlock();
bb.readXML(...
parser.addBehaviourBlock(bb);

The result of the parse is a list of constraints and behaviours that can be obtained using the parser.getBehaviours() and parser.getConstraints() function. The parser may resolve constraints over multiple BehaviourBlocks (not tested very thoroughly), but typically it is cleaned using parser.clean() with each new block to parse.

Making use of BML extension mechanisms in OpenBMLParser

Using custom BML attributes in core (or other) behaviors

BML behaviours may contain custom attributes. For example:

<gesture id="g1"lexeme="BEAT"
xmlns:customattr="http://www.custom.com" customattr:amplitude="3">

Your custom amplitude attribute has to be registered as a gesture specific custom attribute as follows:

BMLInfo.addCustomFloatAttribute(GestureBehaviour.class,
"http://www.custom.com","amplitude");

Then you can use

float value =
behavior.getFloatParameterValue("http://www.custom.com:amplitude");

or

String value =
behavior.getStringParameterValue("http://www.custom.com:amplitude");

to obtain the value of the custom amplitude attribute.

Using custom behavior elements

Custom behaviours are constructed by creating a class for them that extends Behaviour. The custom behaviour class should be registered as follows:

BMLInfo.addBehaviourType(CustomBehaviour.xmlTag(), CustomBehaviour.class);

saiba.bml.AbstractBehaviourTest (in openbmlparser-test.jar) provides a test set for such custom behaviours. See for example saiba.bml.ext.FaceFacsBehaviourTest for an example of its usage.

Using description extensions

Description extensions are to be implemented as classes that extend Behaviour. They are registered as follows:

BMLInfo.addDescriptionExtension(CustomExtBehaviour.xmlTag(), CustomExt.class);

Using custom composition elements and attributes within the BML element

BML blocks may contain composition elements beyond those of core BML, and custom attributes may be used within a bml block (rather than within a behaviour). For example, AsapRealizer allows a preplan attribute to be used within bml, and provides the CHUNK-AFTER composition. Example:

<bml xmlns="http://www.bml-initiative.org/bml/bml-1.0" id="bml1"
composition="CHUNK-AFTER(bml2,bml3)" xmlns:bmlt="http://hmi.ewi.utwente.nl/bmlt"
bmlt:preplan="true">

To handle such elements, a BMLBehaviorAttributeExtension can be defined:

class BMLBBMLBehaviorAttributes implements BMLBehaviorAttributeExtension 
{
    void decodeAttributes(BehaviourBlock bb, 
    HashMap<String, String> attrMap, XMLTokenizer tok)
    {
        //handle custom attributes
        //e.g. 
        boolean prePlan = bb.getOptionalBooleanAttribute(
        "http://hmi.ewi.utwente.nl/bmlt:preplan", attrMap, false);
    }
    
    BMLBlockComposition handleComposition(String sm)
    {
        //Parse the composition mechanism. If this extension cannot parse it, return 
        //CoreSchedulingMechanism.UNKOWN, so that another extension may try to take it.
    }
}

This BMLBehaviorAttributeExtension is then provided to the BehaviourBlock:

BMLBBMLBehaviorAttributes bbmlbExt = new BMLBBMLBehaviorAttributes();
BehaviourBlock block = new BehaviourBlock(bbmlbExt);

Parsing BML feedback

A BML Realizer provides e.g. the behavior planner with various types of feedback. Progress feedback gives information on the execution state of ongoing behaviors or BML blocks. Prediction feedback provides the expected timing of behaviors and or BML blocks. Warning feedback indicates that some behavior(s) failed. See also http://www.mindmakers.org/projects/bml-1-0/wiki/Wiki#Feedback

OpenBMLParser provides a parser for the different types of feedback and provides a class for each of them, wrapping their feedback information.

To parse the feedback String feedback:

BMLFeedback fb = BMLFeedbackParser.parseFeedback(feedback);
if (fb instanceof BMLBlockProgressFeedback)
{
    BMLBlockProgressFeedback bpf = (BMLBlockProgressFeedback) fb;
}
else if(fb instanceof BMLSyncPointProgressFeedback)
{
    BMLSyncPointProgressFeedback spf = (BMLSyncPointProgressFeedback) fb;
}
else if(fb instanceof BMLPredictionFeedback)
{
     BMLPredictionFeedback pf = (BMLPredictionFeedback) fb;
}
else if(fb instanceof BMLWarningFeedback)
{
     BMLWarningFeedback wf = (BMLWarningFeedback) fb;
}

Programmatic, dynamic construction of BML blocks in Java

OpenBMLParser provides the BehaviourBlockBuilder that allows one to easily construct BML blocks from within Java. This allows:

  • Author-friendly BML block construction in which the BML author is guided by the specific types and attributes that are allowed for each behavior and constraint.
  • Easy construction of BML blocks that contain dynamic parameters that are filled out at runtime in the Java program

Some examples:

 BehaviourBlockBuilder builder = new BehaviourBlockBuilder();
 BehaviourBlock bb = builder.id("bml1")
                            .addHeadBehaviour("h1", "NOD",0.7f)
                            .build();
 String bmlBlock = bb.toBMLString());
 
 Constructs the BML block

 <bml id="bml1" xmlns="http://www.bml-initiative.org/bml/bml-1.0">
   <head id="h1" lexeme="NOD" amount="0.7"/>
 <bml>

Or

BehaviourBlock bb = builder
            .id("bml1")
            .addSpeechBehaviour("speech1", "Hello world")
            .addHeadBehaviour("h1", "NOD")
            .addAtConstraint("speech1","start","h1","end")
            .build();

Constructs the BML block

<bml id="bml1" composition="MERGE" xmlns="http://www.bml-initiative.org/bml/bml-1.0">
  <constraint>
    <synchronize>
      <sync ref="bml1:speech1:start"/>
      <sync ref="bml1:h1:end"/>
    </synchronize>
  </constraint>
  <speech id="bml1:speech1">
    <text>Hello world</text>
  </speech>
  <head lexeme="NOD" repetition="1" amount="0.5" id="bml1:h1"/>
 </bml>
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.