Difference between revisions of "Scriptlet"

From PresenceWiki
Jump to: navigation, search
(Scriptlets)
Line 1: Line 1:
 
=== Scriptlets ===
 
=== Scriptlets ===
  
Scriptlets are bits of Java code which can appear in a dynamic text area which will be compiled and executed at runtime.
+
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 far more inline flexibility.
  
 
Scriptlets are identified by surrounding <java> tags, for example:
 
Scriptlets are identified by surrounding <java> tags, for example:
Line 9: Line 9:
 
</java>
 
</java>
  
In order to correctly compile and run, Presence must know the location of the Java compiler. This can be set in [[presenceconfig.xml]].
+
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 - this can be downloaded here:
 +
 
 +
http://www.oracle.com/technetwork/java/javase/downloads/index.html
  
 
=== Purpose ===
 
=== Purpose ===

Revision as of 14:53, 3 February 2011

Scriptlets

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 far more inline flexibility.

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

<java> .... some 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 - this 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.

Pre-built methods

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

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.