OpenWGA 7.5 - OpenWGA Concepts and Features

Design and development » TMLScript

Accessing Java and the WGAPI

Besides using JavaScript objects TMLScript also allows usage of Java objects and classes.

Under the hood TMLScript is processed using Rhino, a JavaScript engine built by the Mozilla group for the Java platform. It provides extensive access to the Java resources that are provided by the OpenWGA host process. This chapter outlines how these Java resources are utilized in TMLScript.

Creating and using Java objects

Creating simple Java objects in TMLScript is easy and resembles the creation of normal JavaScript objects:

var st = new java.util.Stack();

TMLScript takes care of converting String, Number and Boolean values between JavaScript and Java. So you can issue JavaScript objects to Java methods that need their Java pendants as arguments. Return values of these methods will also be backconverted to JavaScript objects.

st.add("Entry"); // Adds a java.lang.String
st.add(5);  // Adds a java.lang.Double

st.add(true); // Adds a java.lang.Boolean


if (st.size() == 3) { // Direct comparison between Java int and JavaScript Number

  log.info("Correct size!");

}


var e1 = st.pop() // Returns a JavaScript Boolean

var e2 = st.pop() // Returns a JavaScript Number

var e3 = st.pop() // Returns a JavaScript String


this.setvar("stack", st);

As seen Java objects can also be stored inside JavaScript and WebTML variables.

This simple way of instantiation is possible for all classes whose package name starts with "java.". For other packages the package name needs to be prefixed with keyword "Packages.".

var myBean = Packages.de.innovationgate.beans.MyBean();
myBean.doSomething();

It is also possible to call static methods and properties on Java objects, just by addressing the class and calling the method:

return Packages.de.innovationgate.beans.MyBean.getVersionString();

TMLScript can use all Java classes that are available in the OpenWGA classpath. To make a Java library available to TMLScript the most easy way is to drop the corresponding JARs into the system file container of any OpenWGA design that is used by an app on your server.

Accessing bean properties

TMLScript provides special features for Java methods that follow the bean accessor syntax:

var oldName = myObject.getName();
myObject.setName(newName);

While TMLScript of course allows them to be called as normal methods they are also accessible in property syntax. So the following example is equivalent to the previous one:

var oldName = myObject.name;
myObject.name = newName;

Using Java derivates of native TMLScript objects

Some Java objects in are automatically converted to their JavaScript counterparts in TMLScript, like Strings any Numbers or Booleans. This is ok and necessary in most situations. However in some situations you might want to operate on the Java object and not on the native JavaScript object, for example if the Java object has some methods that the JavaScript counterpart does not provide.

In that case you can use the method WGA.javaObject() on that native JavaScript object to unwrap it into the Java object. The following example uses this to access the method getBytes() on the Java string and retrieve the native UTF-8 bytes representing it:

WGA.javaObject(myString).getBytes("UTF-8")

The WGAPI

The WGAPI (short for WGA API) is a core component of OpenWGA which is responsible for interacting with OpenWGA content stores and data sources. It is an object-oriented Java library that is utilized by the OpenWGA server itself to interact with the available data.

TMLScript has some interfaces to the WGAPI and the WGAPI objects that OpenWGA creates and uses.  The method this.db() for example returns the WGAPI database object of the content store or data source that currently is in context. This object allows direct interaction with the documents that are stored in the database, like the following example shows:

var areaList = db().getAreas().iterator();
var result = "";
while (areaList.hasNext()) {
  var area = areaList.next();
  result += area.getName() + "<br/>";
}
return result;


This little example retrieves all website area documents from the WGAPI database object, which itself are WGAPI document objects. It then iterates over the areas (using an Java iterator) and concatenates the names of all areas into a result string.

The method this.content() returns the WGAPI document object that represents the current content document in context. In the following example some properties of this object are read. The object also provides properties that retrieve all related documents of the content, like its struct entry and again the area it resides in. The example reads properties of them too:

var con = content();
var contentTitle = con.title;
var structTitle = con.structEntry.title;
var areaName = con.structEntry.area.name;


The WGAPI can be used for all operations that are available on the accessed database, including the creation of content documents. You however need some basic understanding of the document types of the content store and their relations to do this, as on content creation you will need to specify these relations. 

Here is an example which creates a complete page of content type "standard" for language "en". The page is created in the root of area "newdocs". Also an item "created" is set to the current datetime:

var lang = db().getLanguage("en");

var ct = db().getContentType("standard");

var area = db().getArea("newdocs");

var newDoc = area.createRootPage(ct, lang, "The new doc");

newDoc.setItemValue("created", WGA.createDate());

newDoc.publish();

The WGAPI library and its capabilities is documented in the WGAPI and HDB API reference, a documentation in Javadoc format. Note also the security advice on the homepage of this reference.