Scriptlet

From PresenceWiki
Revision as of 16:45, 9 February 2011 by Mattpryor (Talk | contribs)

Jump to: navigation, search

Scriptlets

http://www.international-presence.com/wikidocs/images/java_logo.png


Overview

Scriptlets are bits of Java code which can appear in a dynamic text area which will be compiled and executed at runtime. They provide similar functionality to Presence Functions but unlike functions are dynamically compiled. To summarize, you can use Scriptlets where you want complex functionality within a Task element but do not want to write a re-usable function.

Scriptlets are identified by surrounding <java> tags, for example:

<java> .... some Java code ... </java>

Purpose Of Scriptlets

Scriptlets allow you to:

  • Link Presence to your Java libraries
  • Easily include complex code and logic in a single Node
  • Perform tasks which would be lengthy or difficult to do using only Task nodes.

How Scriptlets Work

When Presence finds the special <java> tags in a Task Element it knows that whatever is between the tags needs to be compiled by the Java compiler (usually javac.exe). A new class is created which extends com.internationalpresence.script.ScriptAbstract, and the abstract method public void userCode() is dynamically replaced with the scriptlet contents.

If compilation is successful the new Class is imported into Presence for use by any servers or clients and is stored in the Presence database.

Note that you can view the compiled class in the Jar Manager under "Loose Classes" - the class name will be something along the lines of com.internationalpresence.tmp.Tempxxxxxxxxxxxxxx. (For people who are interested, the classname is based on an MD5 hash of the containing code)

These temporary classes are retained for 30 days and are deleted if unused when the Database Server initiates, so your scriptlets will need to be recompiled if they are not referenced after this time (see Compilation Time, below).


Specifying the Java Compiler Location

In order to correctly compile and run, Presence must know the location of the Java compiler. This can be set in presenceconfig.xml:

http://www.international-presence.com/wikidocs/images/javac_config.png

The first "part" element should contain the location of the javac executable, or equivalent. Note that you must have a Java compiler installed in order for this to work - the Oracle JDK can be downloaded here:

http://www.oracle.com/technetwork/java/javase/downloads/index.html


Importing classes and packages

As with a Java class, it is necessary to import any classes or packages which are not referenced explicitly. For example, if you wish to reference the java.util.HashMap class you will need to import the class or the java.util.* package. To do this, add an "import" attribute to the scriptlet's <java> tag, for example:

http://www.international-presence.com/wikidocs/images/scriptlet_imports.png

Multiple classes or packages can be imported by separating them with semicolons (;), e.g.:

<java import="java.net.*;java.io.*;java.util.*">

The Scriptlet Editor

Presence has a built-in Scriptlet Editor for writing and compiling scriptlets. To access it, press control+j in a Presence Text Area, or right-click and select "Helpers > Scriptlet Editor" from the pop-up menu (as of Presence 3.6.3)

Compile errors

If the scriptlet cannot be compiled the cause will be displayed in the logs. This should help with ironing out any problems. For example, in the following code we have mis-spelled the "write" method:

http://www.international-presence.com/wikidocs/images/scriptlet_bad.png


And a look at the logs reveals the cause of the problem:

http://www.international-presence.com/wikidocs/images/scriptlet_error_example.png


Compilation time

The first time a scriptlet runs it will take a little while for the compiler to generate the Java class associated with it - usually a few seconds. Assuming the scriptlet does not change after this it will run pretty much immediately thereafter. The time taken for the initial compilation depends on the speed of your processor, length of the script, and other factors.

Available methods

You can make calls to the following methods within your scriptlet code.

public void write (Object o)

This method writes the String value of "o" back to the calling Task Element, in the place where the scriptlet tags were found.

For example:

<java>
write ("Hello Presence");
</java>

Will result in:

Hello Presence

And:

<java>
write ("2+2="+(2+2));
</java>

Will result in:

2+2=4

public void writeln (Object o)

The writeln method does the same as the write method, but appends a newline after the String that is written.

protected PresenceContext getContext()

Returns the current Presence Context, from which you can perform many operations. Since the PresenceContext class is not publicly documented however, we do not support this usage.

protected StringWriter getWriter()

This method returns the StringWriter that is used to write back to the invoking Task Element, should you need a reference to it.

protected Object getValue (String key) throws ScriptletException

This method allows you to perform dynamic lookups on the current data table and variables set. For example, if you have a data table in the Presence Context which contains the columns FORENAME and SURNAME and you wish to refer to the value of SURNAME, you could use:

Object surname = getValue(":var{SURNAME}");

This acts on the current row, and the scriptlet will be invoked multiple times where multiple records are present and referenced in the scriptlet where appropriate - see Iteration Strategies.

Examples

Here are a couple of examples of uses of scriptlets within Presence Task Elements.

Example 1: Format Surnames

The scenario is that we have a database with surnames. However, the data entry person that typed them all was a little careless and didn't properly capitalise the first letter of each surname. So instead of "Jones" we may have "jones" or even "JONES" etc. Assuming the surname is stored in a column named "SURNAME", this append column node will fix the problem:

http://www.international-presence.com/wikidocs/images/scriptlet_example_1.png

Here is an explanation of what's going on:

  • Line 1: Assign the value of the column "SURNAME" to the String "surname".
  • Line 2: Convert the entire surname to lower case
  • Line 3: Create a new String called "nicer" which is the first letter (capitalised) plus the remainder of the word
  • Line 4: Output this back to the Append Column node.

Example 2: Convert height from inches to centimetres

Imagine that we now have a data table containing a building's measurements. However, the lengths are stored in inches and we need to send a report to some French clients, who won't understand that. So here's a scriptlet which does the conversion:

http://www.international-presence.com/wikidocs/images/scriptlet_example_2.png

  • Line 1: Assign the value of the LENGTH column to the variable "inches".
  • Line 2: Multiply this by 2.54 and store it in the variable "cm".
  • Line 3: Output this value to the Append Column node.

Example 3: Output OS and JVM information to Set Variable Node

This shows how you can use scriptlets to access Java system information such as the operating system name and version, and the JVM vendor and version:

http://www.international-presence.com/wikidocs/images/scriptlet_example_3.png