C JAVA & PbML

As we have seen, one can integrate PbML with Java code. Such code can then be called from within a PbML script, using the usual library call syntax

<library>::<service>(..params..).

Let us see how a Java class should be written in order to be used as a PbML library.

• the class must import "yagga.lib.*"
• the class should be public
• the class must have an empty constructor, with no parameters
• every method we want to "export" as a service to PbML must be static
• only the following types can be used as arguments or return values:
  void String int Integer float double Float long Long Double boolean Boolean YaggaObject YaggaClass and arrays of the above types. Please remember that in PbML array of scalars are actually arrays of strings.

C.1 YaggaObject

The Java interface YaggaObject is an interface that enables the user to access directly a PbML object, at run-time.

Here we give the methods:

public YaggaClass getYaggaClass();

returns the YaggaClass of the given YaggaObejct. Since PbML is Object oriented, every object in the game must belong to a class.

public String getId();

returns the actual, unique through the entire game, id of the YaggaObject

public YaggaObject getParent();

returns the parent object of the given one. Can be null, if the object has not a parent object. Please remember that only devices have parent objects, which are the objects where the devices appear.

public Object getVar(String id);

returns the current value of the attribute specified in "id". The value returned, if the attribute is a numerical one, is the value at the beginning of the current phase, not the value resulting after "inc XX by", "dec YY to" etc.. The value must be tested with instanceof to understand the type (String, Boolean.. YaggaObject, String[] etc..) if one doesn't know the correct type of the attribute "id".

public void setVar(String id, Object value) throws WrongType;

sets the current value of the attribute specified in "id" to object "Object". Type checking is made, and a WrongType exception can be thrown if types don't match.

The modification affects the value of the attribute at the beginning of the current phase, not the value resulting after "inc XX by", "dec YY to" etc..

The value must be tested with instanceof to understand the type (String, Boolean.. YaggaObject, String[] etc..) if one doesn't know the correct type of the attribute "id". Results are impredictable if, before this call, "inc XX by", "dec YY to", were issued in PbML, since these commands affected an obsolete value.

For example,

a=4 //phase begin ****
inc a by 5; //future value now is 4+5=9
MyLib.doSthing(self);//inside we have... objRef.setVar("a","7");
//at the end of the call a=7
inc a by 3; //future value now is (4+5=9)+3=12 and not 7+3!!
//phase end ******
now a=(4+5+3)=12.

The 7 was lost, because when calculating future value of a attribute, the operations (sums, sbtract, etcc...) are made on a copy of the attribute made at the beginning of the phase.

public Object getFutureVar(String id);

returns the future value of the attribute specified in "id". The value returned, if the attribute is a numerical one, is the value after any "inc XX by", "dec YY to" etc.. that was executed in the current phase, before the library call.

The value must be tested with instanceof to understand the type (String, Boolean.. YaggaObject, String[] etc..) if one doesn't know the correct type of the attribute "id".

public void setFutureVar(String id, Object value) throws WrongType;

sets the future value of the attribute specified in "id" to object "Object". Type checking is made, and a WrongType exception can be thrown if types don't match.

If the attribute is a numerical one, the modification affects the FUTURE value of the attribute, as it is modified with "inc, dec, set to" etc.

The value must be tested with instanceof to understand the type (String, Boolean.. YaggaObject, String[] etc..) if one doesn't know the correct type of the attribute "id".

For example,
a=4 //phase begin ****
inc a by 5; //future value now is 4+5=9
MyLib.doSting(self);//inside we have... objRef.setFutureVar("a","7");
//at the end of the call a=4 (unchanged), but a in the future is 7
//that is, all previous inc a by etc.. are discarded
inc a by 3; //future value now is 7+3=10 and not (4+5)+3!!
//phase end ******
now a=(7+3)=10.

The first "inc a by 5" was lost, because teh call in the Java code resetetd the "current" future value of "a" to 7, ignoring and discarding any previous operations.

public Object getDev(String id) throws WrongType;

returns the specified device. It can be a YaggaObject or a YaggaObject[].

public void setDev(String id, Object value) throws WrongType;

sets the specified device to an Object.

This Object must be a YaggaObject or a YaggaObject[], and type checking is made and a WrongType exception can be thrown if types don't match (i.e. a YaggaObject is assigned to a deviced declared "object[]").

C.2 YaggaClass

The Java interface YaggaClass is an interface that enables the user to access directly a PbML class, at run-time. Here we give the methods:

public String getName();

returns the name of the class

public YaggaObject[] getObjects();

returns an array containing every object (as YaggaObject) found in the current class.

C.3 the yagga.lib.World class

This class is mainly intended as a library for your Java-to-PbML services. It has the following methods, which can be invoked statically:

public static YaggaObject[] getObjects(String className)

returns every YaggaObject of a certain class, as given in the param className.

If className is null, returns every object in the Yagga world.