Difference between revisions of "Scriptlet"

From PresenceWiki
Jump to: navigation, search
(Scriptlets)
(Examples)
Line 99: Line 99:
 
=== Examples ===
 
=== Examples ===
  
Here are a few examples of uses of scriptlets within Presence Task Elements.
+
Here are a couple of examples of uses of scriptlets within Presence Task Elements.
  
 
==== Example 1: Format Surnames ====
 
==== Example 1: Format Surnames ====

Revision as of 11:34, 4 February 2011

Scriptlets

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

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>

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

Purpose

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)

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.*">

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.