Application Developer's Guide
|
 |
 |
|
|
 |
 |
This section describes how to create custom functions in BEA Liquid Data for WebLogic. It contains the following sections:
Liquid Data provides a set of standard functions to use when creating data views and queries. You can also define custom functions in the Liquid Data server repository to use in the Data View Builder or in hand-coded queries. Custom functions, which are implemented as Java methods, allow you to extend the power and functionality of Liquid Data. Queries can invoke custom functions during query execution just as they can standard functions.
You can package Java implementations in a JAR file that is stored in the custom_lib folder of the Liquid Data repository. If any custom functions refer to addition Java libraries that are not stored in the custom_lib folder of the repository, then you must specify those folders in the Liquid Data CLASSPATH that you configure on the General tab in the Liquid Data node of the Administration Console. For more information, see Configuring Liquid Data Server Settings in the Liquid Data Administration Guide.
.CFLD) file, as described in Step 2: Create the Custom Functions Library Definition File.A function library is a collection of one or more declared custom functions that Liquid Data manages as a single unit. Each function library usually corresponds to a Java class file that contains the function implementations. However, the function library can also reference functions that are implemented in several Java class files. You store custom functions library definition files in the custom_functions folder of the Liquid Data repository.
Once configured as custom functions, descriptions in the Liquid Data server repository will show up as functions available for use in any Data View Builder client or hand-coded XQuery that connects to this server.
This section describes the sequence of tasks for defining custom functions for use in the Data View Builder. The process of defining custom functions involves the following steps:
Once a custom function is created, declared, and registered, you can invoke them in queries created using the Data View Builder.
To define a custom function, you first write its implementation in Java and then compile it. The custom function implementation can exist in a single or multiple Java class files. A single Java class file can contain implementations of multiple custom functions. You package Java implementation in a JAR file that is stored in the custom_lib folder of the Liquid Data repository.
For examples of custom function implementations, see:
When writing a custom function, you must comply with the following rules:
The following table describes the correspondence between XML and Java data types.
Note: For XML data types, the xs prefix corresponds to the XML schema namespace described at the following URL: http://www.w3.org/2001/XMLSchema.
After implementing a custom function in Java, you must declare the custom function in a custom functions library definition (CFLD) file. A CFLD file describes each custom function in a structured XML format. You store custom functions library definition files in the custom_functions folder of the Liquid Data repository.
For examples of custom function implementations, see:
A CFLD file contains the following information:
A CFLD file has the following structure:
Listing 8-1 Structure of a CFLD File
<?xml version = "1.0" encoding = "UTF-8"?>
<definitions>
<types>
<xs:schema> complex types </xs:schema>
</types>
<functions>
<function name="Name of the function" return_type="Return Type"
class="Implementation class" method="Implementation method"
asynchronous="boolean value"? > *
<argument type="Argument Type" label="Argument label"/> *
<presentation group="Data View Builder Presentation Group" />
<description>Function Description</description>
</function>
</functions>
</definitions>
The following table describes the elements in a CFLD file.
After implementing a custom function and creating the CFLD file, you must register the custom function using the Administration Console. Registration involves the following tasks:
custom_lib folder and custom_functions folder, respectively, in the Liquid Data Server repository.For detailed instructions, see Configuring Access to Custom Functions in the Liquid Data Administration Guide.
This section provides examples of custom functions that use simple and complex types. It includes the following sections:
This example shows how to create, declare and use custom functions that operate on simple types.
The following Java code implements custom functions. These functions implement a simple echo operation that returns its argument back to the caller.
Listing 8-2 Java Code for Custom Functions That Use Simple Types
package cf;
import java.math.*;
import java.util.Date;
public class CustomFunctions
{
public static BigDecimal echoDecimal(BigDecimal v)
{
return v;
}
public static Integer echoInteger(Integer v)
{
return v;
}
public static Float echoFloat(Float v)
{
return v;
}
public static String echoString(String v)
{
return v;
}
public static Boolean echoBoolean(Boolean v)
{
return v;
}
public static Calendar echoDateTime(Calendar v)
{
return v;
}
public static Long echoLong(Long v)
{
return v;
}
public static Short echoShort(Short v)
{
return v;
}
public static Byte echoByte(Byte v)
{
return v;
}
public static Double echoDouble(Double v)
{
return v;
}
}
The following sample CFLD file declares the custom functions for simple types.
<?xml version = "1.0" encoding = "UTF-8"?>
<definitions>
<types>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
</xs:schema>
</types>
<functions>
<function name="echoString" return_type="xs:string"
class="cf.CustomFunctions" method="echoString" >
<argument type="xs:string" />
</function>
<function name="echoBoolean" return_type="xs:boolean"
class="cf.CustomFunctions" method="echoBoolean" >
<argument type="xs:boolean" />
</function>
<function name="echoByte" return_type="xs:byte"
class="cf.CustomFunctions" method="echoByte" >
<argument type="xs:byte" />
</function>
<function name="echoShort" return_type="xs:short"
class="cf.CustomFunctions" method="echoShort" >
<argument type="xs:short" />
</function>
<function name="echoInteger" return_type="xs:integer"
class="cf.CustomFunctions" method="echoInteger" >
<argument type="xs:integer" />
</function>
<function name="echoLong" return_type="xs:long"
class="cf.CustomFunctions" method="echoLong" >
<argument type="xs:long" />
</function>
<function name="echoFloat" return_type="xs:float"
class="cf.CustomFunctions" method="echoFloat" >
<argument type="xs:float" />
</function>
<function name="echoDouble" return_type="xs:double"
class="cf.CustomFunctions" method="echoDouble" >
<argument type="xs:double" />
</function>
<function name="echoDecimal" return_type="xs:decimal"
class="cf.CustomFunctions" method="echoDecimal" >
<argument type="xs:decimal" />
</function>
<function name="echoDateTime" return_type="xs:dateTime"
class="cf.CustomFunctions" method="echoDateTime" >
<argument type="xs:dateTime" />
</function>
</functions>
</definitions>
After the function library is registered in Liquid Data, it can be called from the following query (mycf is the logical name specified in the CFLD file):
let
$es:=mycf:echoString("hello"),
$ebool:=mycf:echoBoolean(xf:true()),
$eb:=mycf:echoByte(cast as xs:byte("127")),
$eh:=mycf:echoShort(cast as xs:short("32767")),
$ei:=mycf:echoInteger(cast as xs:integer("2147483647")),
$el:=mycf:echoLong(cast as xs:long("9223372036854775807")),
$ef:=mycf:echoFloat(cast as xs:float("1.0")),
$ed:=mycf:echoDouble(cast as xs:double("2.0")),
$edec:=mycf:echoDecimal(cast as xs:decimal("1.5")),
$edateTime:=mycf:echoDateTime(cast as xs:dateTime("1999-05-31 13:20:00.0")),
return
<echo>
<string>{$es}</string>
<boolean>{$ebool}</boolean>
<byte>{$eb}</byte>
<short>{$eh}</short>
<integer>{$ei}</integer>
<long>{$el}</long>
<float>{$ef}</float>
<double>{$ed}</double>
<decimal>{$edec}</decimal>
<dateTime>{$edateTime}</dateTime>
</echo>
This example shows how to create, declare and use a custom function that takes a complex type as a parameter and returns a complex type.
The following Java code implements a custom function for a complex type. This function simply returns its parameter.
Listing 8-3 Custom Function for a Complex Type
package mycf;
import org.w3c.dom.Element;
public static Element echoElement(Element v)
{
return v;
}
The following sample CFLD file declares the custom function for a complex type.
Listing 8-4 CFLD File That Declares the Custom Function for a Complex Type
<?xml version = "1.0" encoding = "UTF-8"?>
<definitions>
<types>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name = "book">
<xs:complexType>
<xs:sequence>
<xs:element ref = "title"/>
<xs:element ref = "author" maxOccurs = "unbounded"/>
<xs:element ref = "publisher"/>
<xs:element ref = "price"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name = "title" type = "xs:string"/>
<xs:element name = "author">
<xs:complexType>
<xs:sequence>
<xs:element ref = "last"/>
<xs:element ref = "first"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name = "publisher" type = "xs:string"/>
<xs:element name = "price" type = "xs:string"/>
<xs:element name = "last" type = "xs:string"/>
<xs:element name = "first" type = "xs:string"/>
</xs:schema>
</types>
<functions>
<function name="echoBook" return_type="book"
class="mycf.CustomFunctions2" method="echoElement" >
<argument type="book" />
</function>
</functions>
</definitions>
After the function is registered in Liquid Data, it can be called from the following query:
Listing 8-5 Sample Query That Uses the Custom Function for a Complex Type
for $b in document("bib")//book
let $c:=echoBook($b)
return
<ans>
{
for $t in $c/title
return $t
}
</ans>
|
|
|