NAME

VOTABLE::STREAM - VOTABLE STREAM XML element class


SYNOPSIS

 use VOTABLE::STREAM;


DESCRIPTION

This class implements the STREAM element from the VOTABLE DTD. This element is used to encapsulate streams of arbitrary data, possibly encoded and/or compressed.

The STREAM element is a Tier 0 element, and is described by the following excerpt from the VOTABLE 1.0 DTD:

 <!ELEMENT STREAM (#PCDATA)>
 <!ATTLIST STREAM
         type (locator | other) "locator"
         href CDATA #IMPLIED
         actuate (onLoad | onRequest | other | none) "onRequest"
         encoding (gzip | base64 | dynamic | none) "none"
         expires CDATA #IMPLIED
         rights CDATA #IMPLIED
 >

Methods

new($str_or_ref, %options)

Create a new VOTABLE::STREAM object, and return a reference to it. If the first argument ($str_or_ref) is a string, it is used as the initial #PCDATA content of the STREAM element. If the first argument is a reference to a XML::DOM::Element object, that object is used to initialize the new STREAM element (implicitly assuming that the XML::DOM::Element object contains a valid STREAM element). The %options hash is used to set the attributes of the new element. If the first argument is missing or undefined, or an empty string, create and return an empty VOTABLE::STREAM object. Return undef if an error occurs.

get_actuate

Return the value of the actuate attribute. Return undef if the attribute has not been set, or an error occurs.

set_actuate($actuate)

Set the value of the actuate attribute to the specified value. The new value is checked for correctness against the list of allowed values. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

get_encoding

Return the value of the encoding attribute. Return undef if the attribute has not been set, or an error occurs.

set_encoding($encoding)

Set the value of the encoding attribute to the specified value. The new value is checked for correctness against the list of allowed values. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

get_expires

Return the value of the expires attribute. Return undef if the attribute has not been set, or an error occurs.

set_expires($expires)

Set the value of the expires attribute to the specified value. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

get_href

Return the value of the href attribute. Return undef if the attribute has not been set, or an error occurs.

set_href($href)

Set the value of the href attribute to the specified value. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

get_rights

Return the value of the rights attribute. Return undef if the attribute has not been set, or an error occurs.

set_rights($rights)

Set the value of the rights attribute to the specified value. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

get_type

Return the value of the type attribute. Return undef if the attribute has not been set, or an error occurs.

set_type($type)

Set the value of the type attribute to the specified value. The new value is checked for correctness against the list of allowed values. Use undef as the argument to clear any existing value of the attribute. Return the new value of the attribute on success, or undef if an error occurs.

actuate

Read the content of the stream from the source specified by the href attribute, and store it internally. Return true (1) on success, and false (0) if an error occurs.

get_content($offset, $length)

Return a portion of the content string starting at $offset bytes and continuing for $length bytes. If $offset and $length are not specified, return the entire content as a single byte string. If $offset is specified but $length is not, return the content from $offset to the end of the string. Otherwise, the $offset and $length arguments are treated the same as the corresponding arguments to the substr subroutine. If required, the stream content is actuated (by calling the actuate method) prior to extracting the content. Return the content as a string, or undef if an error occurs.

set_content($bytes, $offset, $length)

Set the specified portion of the content of the STREAM, starting at $offset and continuing for $length bytes, to the specified byte string. If $offset and $length are not specified, the current content is replaced by the specified byte string. If $offset is specified but $length is not specified, $length defaults to the length of $bytes. Otherwise, $offset and $length behave as the corresponding arguments to substr. Return the new string on success, or undef on error.

serialize

Write the current content string to the location specified by the href attribute, using the current value of the encoding attribute. Return true (1) on success, or false (0) on error.

Notes on class internals


WARNINGS


SEE ALSO

VOTABLE, VOTABLE::BINARY, VOTABLE::FITS


AUTHOR

Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)


VERSION

$Id: STREAM.pm,v 1.1.1.15 2002/06/09 21:13:08 elwinter Exp $