Charlie API Reference

CharlieException()

.global

Summary

This object is used for error propagation from actions.

Syntax

       CharlieException()

Example

       ex = new CharlieException();
       ex.code = 1234;
       ex.msg = "bad event";
       throw ex;

Notes

Set different properties to see them in the report log.

Summary

This object allows to access the internal Sablotron structures using the subset of DOM level 1 calls. It may be used as a factory for new documents or as an wrapper around DOM documents returned from modules. This object extends the Node object.

Syntax

       new DOMDocument([handle])

Name	Type	Description
`handle`	`PerlValue`	the internal document handle returned form the module - optional

Example

       doc = new DOMDocument();
       root = doc.createElement("root");
       doc.appendChild(root);

Summary

set.get the autodispose flag of the document. If this flag is set, the resources allocated by Sablotron are disposed, when the JS variable gets out of its scope. The default is true.

Syntax

       autodispose([flag])

Name	Type	Description
`flag`	`boolen`	the flag - optional

Example

       doc.autodispose(0);

Notes

You usually don't need change the default value.

Summary

Clone given Node and set itself as the owning document. Deep copy is supported.

Syntax

       cloneNode(node, deep)

Name	Type	Description
`node`	`Node`	the node to be cloned
`deep`	`boolean`	indicates whether the subtree is to be cloned

Example

       root = doc1.cloneNode(doc2.getFirstChild());
       doc1.appendChild(root); //copy the whole document

Summary

Create new CDATA section node. It works exactly like DOMDocument.createTextNode(); the only difference is serialization of this node.

Syntax

       createCDATASection(value)

Name	Type	Description
`value`	`string`	the node content

Example

       doc.createCDATASection("my data");

Summary

Create new comment node.

Syntax

       createComment(value)

Name	Type	Description
`value`	`string`	the node content

Example

       doc.createComment("the reason is this and that");

Summary

Create new Element of given name.

Syntax

       createElement(name)

Name	Type	Description
`name`	`string`	the new element name

Example

       e = doc.createElement("book");

Summary

Create new processing instruction node.

Syntax

       createProcessingInstruction(target, data)

Name	Type	Description
`target`	`string`	the target application
`data`	`string`	the PI data

Example

       doc.createProcessingInstruction("myapp", "mydata");

Summary

Create new text node of given content.

Syntax

       createTextNode(value)

Name	Type	Description
`value`	`string`	the node content

Example

       doc.createTextNode("my data");

Summary

Serialize the document.

Syntax

       docToString()

Example

       str = doc.docToString();

Notes

Many functions accepting the XML documents as a parameter accept the DOMDocument directly.

Summary

Free the document immediately.

Syntax

       freeDocument()

Example

       doc.freeDocument();

Notes

Do it for HUGE documents only to. All documents are disposed at the end of the action by default.

Summary

Object for element node representation. Extends the Node object, adds some attribute handling methods.

Syntax

       Element(handle)

Name	Type	Description
`handle`	`PerlValue`	the internal perl handle of the node

Example

       element = new Element(handle);

Notes

Never use this contstructor directly! Use the factory methods of the DOMDocument object.

Summary

Get the value of the specified attribute.

Syntax

       getAttribute(name)

Name	Type	Description
`name`	`string`	the name of the attribute

Example

       value = element.getAttribute("href");

Summary

Remove the specified attribute the element.

Syntax

       removeAttribute(name)

Name	Type	Description
`name`	`string`	the name of the attribute

Example

       element.removeAttribute("href");

Summary

Set the attribute of the element node.

Syntax

       setAttribute(name, value)

Name	Type	Description
`name`	`string`	the name of the attribute
`value`	`string`	the value if the attribute

Example

       element.setAttribute("href", "mydoc.xml");

Summary

This object represents a part of MultipartFormData.

Description

This object represents a part of MultipartFormData. The MultipartFormData is Request.parsedContent() of a request that delivers POSTed "multipart/form-data" encrypted HTML form. This form setting is used for files upload.

FormData is similar to MessagePart, except it is strictly read only and its interface is enriched by some methods specific to HTTP form posting and file uploads.

Field metadata details can be accessed using FormData.name(), FormData.header(), FormData.filename() and FormData.size() methods.

Field value can be read out by FormData.value() or FormData.read() method.

Big data (like big uploaded file) manipulation can be easier with knowing of FormData.storageFilename().

Summary

Gets name of uploaded file.

Syntax

       filename()

Description

Multipart/form-data form is used for files uploading. When FormData represents the uploaded file, this method returns the file original name, otherwise, it returns nothing.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var file = mfd.field("file1");
       var origFileName = file.filename();

Summary

Gets field header value.

Syntax

       header(name);

Name	Type	Description
`name`	`string`	name of header field

Description

Read-only access to form field header. Header field names are case-insensitive. See RFC 2388 and RFC 1867 for details.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var name = mfd.field("name");
       var cte = name.header("Content-Transfer-Encoding");

Summary

Gets field name.

Syntax

       name();

Description

Multipart/form-data form may contain several fields with the same name. In this case, the fields must be accessed by their indexes. Name of a particular form data field is then available by calling this method.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       for (i=0; i < 0; i++) {
            var field = mfd.fieldIdx(i);
            var name = field.name();
            ....
       };

Summary

Reads part of field data.

Syntax

       read([size])

Name	Type	Description
`size`	`number [bytes]`	size of data to be read out, in bytes - optional

Description

See MessagePart.value() and MessagePart.read().

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var file = mfd.field("file1");
       var buff = file.read(1024);
       while (buff) {
            // do something with the buffer
            buff = file.read(1024);
       };
       ...
       or
       ...
       var mfd = request.parsedContent();
       var file = mfd.field("file1");
       var data = file.read(); // the same as file.value()

Summary

Gets size of data in the field.

Syntax

       size();

Description

Gets size of data in the field. Size of field headers is not included.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var file = mfd.field("file1");
       var size = file.size();

Summary

Gets name of the temporary file used to store field data.

Syntax

       storageFilename();

Description

See discussions to RawContent.tempFilename() and MessagePart.storageFilename().

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var file = mfd.field("file1");
       var origFileName = file.filename();
       var tempFilename = file.storageFilename();

Summary

Gets field value.

Syntax

       value();

Description

See MessagePart.value() and MessagePart.read().

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       for (i=0; i < 0; i++) {
            var field = mfd.fieldIdx(i);
            var name = field.name();
            var value = field.value();
            ....
       };

Summary

Actions, short JavaScript programs launched as a response to an incoming request are basic building stones of Charlie mosaic.

Description

In Charlie actions, you may use all the constructs defined by the ECMA language specifications, as their are implemented in Mozilla's JavaScript engine version 1.5.
To interact with the Charlie engine, XSLT or DOM processor, etc. there are several global objects available in the JS context. These objects offer either the Charlie engine (core) services or miscellaneous tools useful when designing actions.
In addition to the standard Charlie features, you are allowed to plug your own libraries in Perl or JavaScript in and to create your own API extensions to be called from actions.

Notes

The standard objects are:
Request
Response
URI
Query
Sablotron
DOMDocument
Element
Node
Mail
RawContent
MultipartMessage, MessagePart
MultipartFormData, FormData

Summary

E-mail sender object representation.

Syntax

       Mail()

Example

       mail = new Mail();
       mail.from("sender@domain.com");
       mail.to("receiver@domain.com");
       mail.subject("Good News");
       mail.send("This mail is generated by Charlie");

Notes

The underlaying code attempts to send a message using a mailer deamon (sendmail by default, see Mail.mailer()). If not successful, it looks for Net::SMTP perl module (see Mail.host()). If still not successful, an error is issued.

Summary

Add a line of text to the message to be send.

Syntax

       addBody(txt)

Name	Type	Description
`text`	`string`	message text

Example

       mail.addBody("This mail is generated by Charlie");

Notes

Strings added with addBody method will be separated by a newline character.

Summary

Set the specified header of the message.

Syntax

       addHeader(field, value)

Name	Type	Description
`field`	`string`	the specified field
`value`	`string`	the value of the specified field

Example

       mail.addHeader("Content-type","text/plain; charset=UTF-8");

Notes

There are shortcuts defined for the most common headers (From, Subject, To, Cc, Bcc)

Summary

Set the Bcc header of the message.

Syntax

       bcc(value)

Name	Type	Description
`value`	`string`	the value of the Bcc field

Example

       mail.bcc("receiver@domain.com");

Summary

Set the CC header of the message.

Syntax

       cc(value)

Name	Type	Description
`value`	`string`	the value of the CC field

Example

       mail.cc("receiver@domain.com");

Summary

Set the From header of the message.

Syntax

       from(value)

Name	Type	Description
`value`	`string`	the value of the From field

Example

       mail.from("sender@domain.com");

Summary

Sets a SMTP (remote) host to contacted by Net::SMTP.

Syntax

       host(hostname)

Name	Type	Description
`hostname`	`string`	SMTP host

Example

       mail.host('mail.domain.com');

Notes

The default value is 'localhost'.

Make sure the specified host relay for your 'From' domain.

Summary

Sets a mailer program the formatted message is passed to.

Syntax

       mailer(program)

Name	Type	Description
`program`	`string`	mailer program name

Example

       mail.mailer('/usr/sbin/sendmail');

Notes

The default value is '/usr/sbin/sendmail'.

Use mail.mailer('') to send mails via Net::SMTP explicitly.

Summary

Removes all text from the message body.

Syntax

       removeBody()

Example

       mail.removeBody();

Summary

Removes the specified header of the message.

Syntax

       removeHeader(field)

Name	Type	Description
`field`	`string`	the specified field

Example

       mail.removeHeader("Content-type");

Summary

Sends a message formatted by other methods of this object.

Syntax

       send(txt)

Name	Type	Description
`text`	`string`	message text

Example

       mail.send("This mail is generated by Charlie");

Notes

The string passed to this method is appended to other body text inserted with Mail.addBody() method before. The addBody method can be omitted at all for short messages.

Summary

Set the Subject header of the message.

Syntax

       subject(value)

Name	Type	Description
`value`	`string`	the value of the Subject field

Example

       mail.subject("Good News");

Summary

Set the To header of the message.

Syntax

       to(value)

Name	Type	Description
`value`	`string`	the value of the To field

Example

       mail.to("receiver@domain.com");

Summary

This object represents part of MultipartMessage.

Syntax

       new MessagePart();

Description

MessagePart represents a part of a MultipartMessage. Since MultipartMessage represents a MIME message, MessagePart represents a part of such a message. As such, the object consists of a set of headers and a body.

For manipulation with headers, use MessagePart.header() method.

MessagePart body is controlled by MessagePart.write(), MessagePart.read() and MessagePart.value() methods. Size of stored data can be get by MessagePart.size().

Internally, data are stored in a structure similar to RawContent object, see its reference for understanding read and write methods. As in the case of RawContent, data are stored in memory or in a temporary file. Object is transparent in this respect. You can read name of temporary file using MessagePart.storageFilename() method, but there is no way how to control storage in a way similar to RawContent.memoryLimit().

Summary

Get/set message part header.

Syntax

       header(name, [value])

Name	Type	Description
`name`	`string`	name of the accessed MessagePart header
`value`	`string`	the new value of the MessagePart header - optional

Description

MessagePart has its own set of headers. Typically, they include Content-type for MIME type of stored data. According to MIME specification (RFC 1521) default value for this header is "text/plain; charset=us-ascii". Header names are case-insensitive.

Use MessagePart.header() method to set, alter or read header values.

Example

       var mp = new MessagePart();
       mp.header("Content-Type") = "text/plain; charset=utf-8";
       .....
       or
       .....
       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);            
       var ct1 = mp.header("Content-Type");
       if (ct1 == "image/jpeg") {    .....

Summary

Reads data stored in object body.

Syntax

       read([size])

Name	Type	Description
`size`	`number [bytes]`	size of buffer to be read out - optional

Description

Usage of this method is similar to that of RawContent.read(), except there is no equivalent of RawContent.resetRead() here. To get all body data, use MessagePart.value() method.

Example

       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);            
       var buff = mp.read(1024);
       while (buff) {
            // do something with the buffer
            buff = mp.read(1024);
       };
       ...
       or
       ...
       var data = mp.read(); // the same as mp.value();

Summary

Returns actual size of message part body size.

Syntax

       size()

Description

Returns actual size of message part body size, i.e. without size of string representation of headers.

Example

       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);            
       var dataSize = mp.size();

Summary

Name of temporary file that contains object body.

Syntax

       storageFilename();

Name	Type	Description
`ct`	`string`	the new value of the MessagePart content type - optional

Description

For big data (bigger than 4096 bytes), a temporary file is created (see MessagePart.write() for details). This method returns name of such a file.

Example

       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);            
       var fileName = mp.storageFilename();

Summary

Returns string representation of the object.

Syntax

       toString()

Description

String representation of a MessagePart consists of headers and body, formated according to MIME specification (RFC 1521).

Example

       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);         
       // returning message part as plain string for debugging purposes
       response.content(mp.toString());

Summary

Read body of the object.

Syntax

       value()

Description

See MessagePart.read().

Example

       var mm = request.parsedContent();  // request posted a MIME data
       var mp = mm.getPart(1);            
       var data = mp.value(); // the same as mp.read();

Summary

Adds data to end of objects body.

Syntax

       write(data)

Name	Type	Description
`data`	`string`	data to be added to end of message part body

Description

This method is used in the same way as RawContent.write() method, except that there is no way how to control actual data storage; memory limit is fixed to 4096 bytes (see RawContent.memoryLimit too).

Example

       var mp = new MessagePart();
       mp.header("Content-Type") = "text/plain; charset=utf-8";
       mp.write("HELLO UNICODE WORLD\n");

Summary

MultipartFormData is a wrapper of POSTed "multipart/form-data" encrypted HTML form.

Description

The MultipartFormData is return value of Request.parsedContent() in the case of POSTed "multipart/form-data" encrypted HTML form. This form setting is used for files upload.

Technically, it is a special case of MultipartMessage object. The object has only three methods. All of them interfaces access to the posted form fields: MultipartFormData.field(), MultipartFormData.fieldIdx() and MultipartFormData.count().

Example

       // action responds to a POSTED multipart/form-data form
       my mfd = request.parsedContent();

Summary

Number of form fields.

Syntax

       count();

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       for (i=0; i < 0; i++) {
            var field = mfd.fieldIdx(i);
            ....
       };

Summary

Gets form field by name.

Syntax

       field(name)

Name	Type	Description
`name`	`string`	name of the accessed field

Description

This method returns fields by their names.

Note, that when a form has more than one field with the same name, only first of these fields is returned with this method. To access all of these fields, use MultipartFormData.fieldIdx() method.

Returned object is of FormData type.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       var file = mfd.field("file1");

Summary

Gets form field by the part index.

Syntax

       fieldIdx(index);

Name	Type	Description
`index`	`number [0, ..]`	accessed field index, indexing starts from 0

Description

It is sometimes useful access form fields not by their names, but by their index, e.g. when a HTML form contains more than one field with the same name. This method servers such a task.

Indexing starts by 0. Overall fields count is provided by MultipartFormData.count() method. Returned object is of FormData type.

See also MultipartMessage.getPart(), which is implemented in the same way.

Example

       // action responds to a POSTED multipart/form-data form
       var mfd = request.parsedContent();
       for (i=0; i < 0; i++) {
            var field = mfd.fieldIdx(i);
            ....
       };

Summary

This object represents MIME message as defined by RFC 1521.

Syntax

       new MultipartMessage();

Description

MultipartMessage is an interface to MIME message. There are two ways how this object appears in Charlie actions:

* it can be returned as Request.parsedContent() or Response.parsedContent(). See documentation of these two methods for details.
* you can create it by calling its constructor (see syntax).

MIME message consists of set of headers and multipart body.

Headers are manipulated by MultipartMessage.header(), MultipartMessage.contentType() and MultipartMessage.boundary() methods.

Particular body parts are represented by MessagePart objects. They can be added by MultipartMessage.addPart() method and accessed by MultipartMessage.getPart() method. MultipartMessage.count() gets message parts count.

In addition, you can use MultipartMessage.size() to get overall size of the object data and MultipartMessage.toString() method to get its string representation.

The MultipartMessage object itself is used by Response and Request objects to hold structured data (both accepted or prepared for delivery). See Request.parsedContent() or Response.parsedContent() methods for details.

Summary

Adds a new part to the multipart object.

Syntax

       addPart(value);

Name	Type	Description
`value`	`MessagePart`	message part to be added

Description

Use this method to add a new part (object of MessagePart type) to multipart message.

Example

       var mm = new MultipartMessage();
       var mp = new MessagePart();
       mp.write("HELLO WORLD");
       ....
       mm.addPart(mp);

Summary

Get/set MIME boundary.

Syntax

       boundary([value])

Name	Type	Description
`value`	`string`	new value of MIME boundary - optional

Description

Particular MultipartMessage parts are detached by a boundary (see RFC 1521 for details).

Boundary is defined as part of message content type header (see MultipartMessage.contentType(), MultipartMessage.header()). Using this method, you can get or change boundary used in the object. It is not necessary to set boundary manually, object constructor generates a random boundary itself upon object creation.

Example

       var mm = new MultipartMessage();
       mm.boundary("my_superunique_boundary");
       .....
       or
       .....
       var mm = request.ParsedContent();
       var bnd = mm.boundary();

Summary

Get/set object content type.

Syntax

       contentType([value])

Name	Type	Description
`value`	`string`	new content type, must contain boundary definition - optional

Description

Use this method to get or change multipart message content type. Multipart message content type is set to
"multipart/mixed; boundary="RandomUniqueBoundary"
by defaults.

When setting a content type, you must supply a boundary definition as part of it! Otherwise, the object couldn't be serialized. Also, if you specify different that "multipart" MIME type, other party may not work with the data properly. See also MultipartMessage.boundary()

For general unstructured data use RawContent object.

Example

       var mm = new MultipartMessage();
       mm.contentType("multipart/x-special; boundary=\"" + mm.boundary() + "\"");

Summary

Number of message parts that constitute the multipart message.

Syntax

       count()

Description

Function gets number of message parts that constitute the multipart message. To get a particular message part, use MultipartMessage.getPart().

Example

       var mm = request.parsedContent();
       for (i=0; i < mm.count(); i++) {
             var part = mm.getPart(i);      
             // do something with the part
       };

Summary

Gets a part of multipart message.

Syntax

       getPart(index)

Name	Type	Description
`index`	`number [0, ..]`	part index, indexing starts from 0

Description

Message parts are stored in an array and are accessible be their indexes that correspond to adding order. Parts indexing starts from 0.

Example

       var mm = request.parsedContent();
       var firstPart = mm.getPart(0);

Summary

Get/set multipart message header.

Syntax

       header(name, [value])

Name	Type	Description
`name`	`string`	name of the accessed header field
`value`	`string`	new value of the accessed header field - optional

Description

Using this method, you can get or change a multipart message header. When a multipart message is provided as a Request or Response parsed content, its headers are synchronized with its provider. The synchronization occurs upon parsing the incoming or departing the outgoing Request or Response.

Special care has to be taken to "content type" header; see MultipartMessage.contentType() reference for details.

By default, a new multipart message has set
Content-Type header to "multipart/mixed; boundary="RandomUniqueBoundary" and
Content-Transfer-Encoding header to "binary".

Header names are case-insensitive.

Example

       var mm = request.parsedContent();
       var xh = mm.header("X-Super-Header");

Summary

Gets overall size of the multipart message.

Syntax

       size();

Description

This function gets overall size of the multipart message, excluding global headers length, but including headers length of message parts and length of boundaries that borders message parts and, of course, sizes of message part bodies.

Compare with MessagePart.size().

Example

       var mm = request.parsedContent();
       var s = mm.size();

Summary

Gets string representation of the object.

Syntax

       toString();

Description

Use this function to get string representation of the multipart message for debug purposes. This function returns the message content in the same manner as MultipartMessage.size() uses it to compute message size.

Do not use this method when feeding Request or Response objects with content method; use parsedContent() method there to get optimal performance and headers synchronization.

Example

       var mm = request.parsedContent();
       // custom method log_it stored its parameter to debug log
       log_it(mm.toString());

Summary

General node object. Used as an ancestor for all node types.

Syntax

       Node(handle)

Name	Type	Description
`handle`	`PerlValue`	the internal perl handle of the node

Example

       node = new Node(handle);

Notes

Never use this contstructor directly! Use the factory methods of the DOMDocument object.

Summary

Append the node to the list of children of the node.

Syntax

       appendChild(newnode)

Name	Type	Description
`newnode`	`Node`	the new (appended) node

Example

       root = doc.createElement("root");
       doc.appendChild(root);

Summary

Test whether then node is equal to other one (represents exactly the same node).

Syntax

       equals(other)

Name	Type	Description
`other`	`Node`	the node to be compared to

Example

       //test whether node is the root node
       node.equals(doc.getFirstChild());

Summary

Get the forst child of the node.

Syntax

       getFirstChild

Example

       child = node.getFirstChild();

Charlie API Reference

Summary

Syntax

Example

Notes

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

Notes

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

Notes

See Also

Summary

Syntax

Example

Notes

See Also

Summary

Syntax

Example

Notes

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Syntax

Example

See Also

Summary

Description

See Also

Summary

Syntax

Description

Example

See Also

Summary

Syntax

Description

Example

See Also

Summary