ECMAScript API Guide

CHAPTER 1

Composer Utility Methods

 
Top of page

Top-Level

The following utility methods and properties are top-level calls, available in any Composer component, wherever ECMAScript can be used. The methods that are described as Composer component methods must be called on theComponent (see description of theComponent further below).

 
Top of section

ERROR

Composer extension object. This object contains the error message and _SystemFault part thrown by Composer whenever an exception occurs. Or it contains the custom Error Message from a Throw Fault action. Has methods getFaultName()

and getFaultPart(). Use it in the Source Expression of a Map action or the Log Expression of a Log action.

 
Top of section

base64Decode(encodedString)

byte[] base64Decode(encodedString)

Composer extension method. This method decodes base64 encoded contents. Returns byte array of decoded binary content. encodedString parameter is of type String (base64 encoded data).

 
Top of section

base64Encode(bytes)

String base64Encode(byte [] byteArray)

Composer extension method. This method base64 encodes input parameter. Returns base64 encoded string. bytes parameter is of type byte[].

 
Top of section

exportObject(key, value)

exportObject (String key, Object value)

Interpreter extension—Composer components. Publishes an object to other called components that use the getExportValue(key) method. key is a string and value is an ECMA or Java object. Example:

  theComponent.exportObject("pubVar", localVar);

 
Top of section

getExportValue(key)

Object getExportValue(key)

Interpreter extension—Composer components. Retrieves an object published from another component that used the exportObject(key,value) method. key is a string value. Example:

  myVar = theComponent.getExportValue("pubVar");

 
Top of section

getFaultName()

String getFaultName()

Composer extension method. Returns the name of the fault contained in the ERROR object.

 
Top of section

getFaultPart()

Document getFaultPart()

Composer extension method. Returns the fault part contained in the ERROR object.

 
Top of section

getLDAPAttr(connection, DN, attrName)

String getLDAPAttr(String connection, String DN, String attrName )

This function returns the value of an attribute from a directory object. Parameters: string connection – name of a LDAP Connection Resource string DN – Distinguished Name of a directory object string attr – name of attribute (value to be returned) Example:

  addr = getLDAPAttr('myCNX','cn=AClark,o=NOVELL','eMailAddress')

 
Top of section

getName()

String getName()

Interpreter extension—Composer components. Returns the name of the currently executing component. Must be called on theComponent.

  theComponent.getName()

 
Top of section

getSessionValue(key)

String getSessionValue (key)

Interpreter extension—Composer components. Obtains a given value previously exported via the putSessionValue() call (see below). Values are available to all components that are called in the same Servlet Session, which may span many html hits. The session life is dependent upon the HTTP Server Session timouts. Please note that this call raises when error when Composer is deployed as an EJB or as a JMS message listener. The key is a String.

 
Top of section

getValidationViaSchemaLocation()

getValidationViaSchemaLocation()

Interpreter extension—Composer components. XML documents which have xsi:schemaLocation or xsi:nonamespaceschemaLocation can use this flag to check whether validation of such documents is done.

 
Top of section

putSessionValue(key, value)

putSessionValue (String key, String value)

Interpreter extension—Composer components. Exports a given value available to all components that are called in the same Servlet Session, which may span many html hits. The session life is dependent upon the HTTP Server Session timouts. These objects are referenced by using the key in an expression (see getSessionValue() below). Please note that this call raises an error when Composer is when deployed as an EJB or as a JMS message listener. The key is a String and the value is a Java object.

 
Top of section

removeSessionValue(key)

removeSessionValue (key)

Interpreter extension—Composer components. Removes a given value previously exported via the putSessionValue() call (see above) Please note that this call raises when error when Composer is deployed as an EJB or as a JMS message listener. The key is a String.

 
Top of section

setValidationViaSchemaLocation(abFlag)

setValidationViaSchemaLocation(abFlag)

Interpreter extension—Composer components. XML documents which have xsi:schemaLocation or xsi:nonamespaceschemaLocation can use this flag to validate the documents. Please note, once set to true it will remain true till the component is closed/end of execution/explicitly set to false again.

 
Top of section

theComponent

This top-level property represents a handle to the xObject in which the script is running. Usually, you will be running scripts from within a Component (e.g., XML Map Component), in which case the property is a Component object reference. Most of the above methods can be called on theComponent.

 
Top of page

I/O Extensions

The following methods are not part of core ECMAScript (and not natively supported in Mozilla Rhino). They are custom extensions implemented by Composer.

 
Top of section

alert(message)

alert(message)

Interpreter extension for Basic I/O. Write a message on the error stream. The message parameter is of type String. In Composer a msgBox is displayed. e.g. alert("The element=" + Input.XPath("root/child") )

 
Top of section

canRead()

boolean canRead()

Interpreter extension—File object method. Returns true if the file exists and is readable.

 
Top of section

canWrite()

boolean canWrite()

Interpreter extension—File object method. Returns true if the file exists and is can be written to.

 
Top of section

clearError()

clearError()

Interpreter extension—File object method. Clears the error indicator.

 
Top of section

close()

boolean close()

Interpreter extension—File object method. Closes a file and returns true if successful.

 
Top of section

confirm(message)

confirm(message)

Interpreter extension for Basic I/O. Ask the user for a confirmation. Returns true or false. The message parameter is of type String.

 
Top of section

eof()

boolean eof()

Interpreter extension—File object method. Return true if the file is at eof or if it is not open for reading. An error is set if the file was not opened for reading.

 
Top of section

error()

String error()

Interpreter extension—File object method. Returns the string of the last error on this file object since it was created or since clearError was called. Returns the empty string (which is equivalent to false) if no error was detected.

 
Top of section

exists()

boolean exists()

Interpreter extension—File object method. Check if the file exists. Return true if the file exists (whether opened or not).

 
Top of section

File(FileName)

File(String fileName)

File constructor. A File object is created by File("pathname"), File("directory","filename"), or simply File( ). The directory can be a File object. Doing toString() on the File object returns fileName.

 
Top of section

flush()

boolean flush()

Interpreter extension—File object method. Flush the output buffer on a file opened for writing. Returns true in case of success.

 
Top of section

getAbsolutePath()

String getAbsolutePath()

Interpreter extension—File object method. Returns the complete path of the file.

 
Top of section

getLength()

number getLength()

Interpreter extension—File object method. Returns the length of the file, 0 if it does not exist.

 
Top of section

getName()

String getName()

Interpreter extension—File object method. Returns the file component part of the path.

 
Top of section

getParent()

String getParent()

Interpreter extension—File object method. Returns the directory part of the file or the parent directory of a directory. Returns a null string if applied to the root directory (of any drive in Windows).

 
Top of section

getPath()

String getPath()

Interpreter extension—File object method. Returns the path given at construction time. Same as toString().

 
Top of section

isAbsolute()

boolean isAbsolute()

Interpreter extension—File object method. Returns true if the path is absolute, false otherwise.

 
Top of section

isDirectory()

boolean isDirectory()

Interpreter extension—File object method. Checks for the existence of a directory. Returns true if the file exists and is a directory.

 
Top of section

isFile()

boolean isFile()

Interpreter extension—File object method. Return true if the file exists and is a regular file (not a directory).

 
Top of section

isopened()

boolean isopened()

Interpreter extension—File object method. Checks if file is already open. Return true if the file is opened (even if at EOF), otherwise return false.

 
Top of section

lastModified()

String lastModified()

Interpreter extension—File object method. Returns the date and time when the file was last modified, or "Jan 1 1970" if it does not exist.

 
Top of section

list()

[Stringarray] list()

Interpreter extension—File object method. Returns list of files or directories in a directory, as an array of strings. Returns null if the File object does not represent a directory.

 
Top of section

load(moduleName)

load(moduleName)

Interpreter extension for Basic I/O. Locate the module in the directories and jar/zip files of the property Interpreter.path or (if the property is not defined) in the classpath (possibly adding the extension ".es", ".esw' or ".js"). Load the module and evaluate its content at run-time.

 
Top of section

mkdir()

boolean mkdir()

Interpreter extension—File object method. Creates the directory or directories specified by the path of the File object if they do not exist. Returns true if the directories were successfully created, false otherwise.

 
Top of section

open()

boolean open()

Interpreter extension—File object method. Open the file for reading if it exists, for writing if it does not exist. Return true if successful. To create a new file, just delete it (using remove()) before calling open.

 
Top of section

prompt(Msg,DefaultText)

prompt(Msg,DefaultText)

Interpreter extension for Basic I/O. Prompt the user for information, proposing the default string. The Msg and DefaultText parameters are of type String.

 
Top of section

readAll()

String readAll()

Interpreter extension—File object method. Open the file, read all text, close the file. Returns the read text as a single string. Returns null in case of error. The file must not be opened when readAll is called!.

 
Top of section

readln()

readln()

Interpreter extension—File object method. Reads a line from an input file. Returns null if at eof or in case of error. It may be more convenient to use the error() routine to check for end of file or error conditions.

 
Top of section

remove()

boolean remove()

Interpreter extension—File object method. Deletes a file. Returns true in case of success. The name remove is used as delete and is an ECMAScript keyword.

 
Top of section

renameTo(newname)

boolean renameTo(newname)

Interpreter extension—File object method. Rename the file to the target name. Target name can be a File object or a string. Returns true if successful.

 
Top of section

separator

separator Interpreter extension—File object property. This property returns the path separator, i.e. the backslash for Windows.

 
Top of section

stderr()

stderr()

Interpreter extension—File object property. This property returns the standard error.

 
Top of section

stdin

stdin Interpreter extension—File object property. This property returns the standard input.

 
Top of section

stdout

stdout Interpreter extension—File object property. This property returns the standard output.

 
Top of section

toString()

String toString()

Interpreter extension—File object method. Returns the path given at construction time. Same as getPath().

 
Top of section

write(...)

boolean write(...)

Interpreter extension—File object method. Write the parameters as a string to the file. Returns true if successful.

 
Top of section

write(...)

write(...)

Interpreter extension for Basic I/O. Write the parameters to the current output stream. The Text parameter is of type String.

 
Top of section

writeln(...)

writeln(...)

Interpreter extension—File object method. Write the parameters as a string to the file, followed by a new line. Returns true if successful.

 
Top of section

writeln(...)

writeln(...)

Interpreter extension for Basic I/O. Write parameters to the current output stream, followed by a new line.

 
Top of page

Database Extensions

These are Composer-defined extensions (not defined in core ECMAScript). For examples of their usage, consult the Custom Scripts resource in the ActionExamples project that ships in Composer's Samples folder.

 
Top of section

connect(URL)

boolean connect(URL)

Interpreter extension—Database object method. Opens a new connection for the specified URL on the DbAccess object. Generates an error if the driver was not correctly initialized. Returns true if connection is successful, false otherwise. Use getLastError to get details on the error.

 
Top of section

connect(URL, userName, password)

boolean connect(URL, userName, password)

Interpreter extension—Database object method. Opens a new connection for the specified URL, with specified user name and password, on the DbAccess object. Generates an error if the driver was not correctly initialized, returns true if connection is successful, false otherwise. Use getLastError to get details on the error.

 
Top of section

Database(driver)

globaldbobject Database(driver)

Interpreter extension Database constructor. Creates an object used to access databases via JDBC. Returns a global database object.

 
Top of section

disconnect()

boolean disconnect()

Interpreter extension—Database object method. Close a connection (do nothing if not connected). Generates an error if the driver was not correctly initialized. Returns true if successful or already disconnected, false in case of error. Use getLastError to get details in case of error.

 
Top of section

executeCommand(sqlString)

arg executeCommand(sqlString)

Interpreter extension—Database object method. Used to implement INSERT, UPDATE, DDL statements and other non-value returning statements. Returns the number of rows impacted if the request is successful, otherwise returns false. If false was returned, getLastError may be called on the database object to get the error information. Note that an error is generated (rather than returning a status) if the connection was not successful.

 
Top of section

executeRetrieval(sqlString)

RowSet executeRetrieval(sqlString)

Interpreter extension—Database object method. Used to implement SELECT and other value returning statements. Return a RowSet object implementing the RowsetAccess protocol if the request is successful. Returns false otherwise. Additional arguments are ignored, and data is always returned as a RowSetAccess. The cursor is positioned before the fist row. If false was returned, getLastError may be called on the database object to get the error information. Note that an error is generated (rather than returning a status) if the connection was not successful.

 
Top of section

getColumnCount()

number getColumnCount()

Interpreter extension—Database RowSet object method. Get the number of columns of this result, identical to the length attribute. Its possible to call this routine before the first record is fetched.

 
Top of section

getColumnDatatypeName()

String getColumnDatatypeName()

Interpreter extension—Database RowSet object method. Get the name of the datatype associated with the column. See the JDBC documentation for details. Some database do not return a valid name, in that case undefined is returned. It is possible to call this routine before the first record is fetched.

 
Top of section

getColumnDatatypeNumber()

number getColumnDatatypeNumber()

Interpreter extension—Database RowSet object method. Get the number of the datatype associated with the column. See the JDBC documentation for details. It is possible to call this routine before the first record is fetched.

 
Top of section

getColumnItem(name)

value getColumnItem(name)

Interpreter extension—Database RowSet object method. Get the value of a column by its name (the value can be accessed by number simply indexing them—this is not faster than by name for Interpreter). The proper value is returned even if the name is used for a property of the RowSetAccess protocol, as next or length. A record must be available (that is next must have been called at least once).

 
Top of section

getColumnName()

String getColumnName()

Interpreter extension—Database RowSet object method. Get the name of a column, in a way which is always working. The names can be accessed as properties, but they are shadowed by the functions and properties of the RowSetAccess prototype object. It is possible to call this routine before the first record is fetched.

 
Top of section

getLastError()

error getLastError()

Interpreter extension—Database object method. Return the last error which occurred when connecting or executing a statement, undefined if none.

 
Top of section

getLastError()

error getLastError()

Interpreter extension—Database RowSet object method. Return the last error which occurred when connecting or executing a statement, null (which test as false) if none.

 
Top of section

getMetaData()

metadata getMetaData()

Interpreter extension—Database object method. Returns the meta data attached to the connection.

 
Top of section

getMetaData()

metadata getMetaData()

Interpreter extension—Database RowSet object method. Return the meta data attached to the row set.

 
Top of section

hasMoreRows()

boolean hasMoreRows()

Interpreter extension—Database RowSet object method. Optimistic view of the possibility that more rows are present. Currently only returns false if next returned false. It is possible to call this routine at any time.

 
Top of section

next()

String next()

Interpreter extension—Database RowSet object method. Get the next row of results. Returns true if there is a next row, false otherwise. Note that next must be called before the first row can be accesses.

 
Top of section

release()

release()

Interpreter extension—Database object method. Equivalent to disconnect, but does not return a status and always succeed. Usually this will release any associated RowSet.

 
Top of section

release()

release()

Interpreter extension—Database RowSet object method. Release the resources attached to this RowSet object. The object should not be accessed after it has been released. The use of release is not mandatory, but is recommended as otherwise the resources (which may include large cache and a database connection) is not reclaimed before the next garbage collection, in this only if it is not reachable anymore.





Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...