new($str_or_ref, %options)
get_actuate
set_actuate($actuate)
get_encoding
set_encoding($encoding)
get_expires
set_expires($expires)
get_href
set_href($href)
get_rights
set_rights($rights)
get_type
set_type($type)
actuate
get_content($offset, $length)
set_content($bytes, $offset, $length)
serialize
VOTABLE::STREAM - VOTABLE STREAM XML element class
use VOTABLE::STREAM;
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 >
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.
_
') are for
internal use only, and should not be used outside of the VOTABLE
class hierarchy.
get_XXX
and set_XXX
accessors for attributes
and elements are derived directly from the names of the attributes or
elements, with the attribute or element name replacing
XXX
. Attribute and element names containing embedded hyphens
('-
') use accessors where the hyphen is mapped to an underscore
('_
') in the name of the accessor method. This is a necessity,
since the hyphen is not a valid name character in Perl.
STREAM
which refers to an external data source (such as a binary
file) nust use the locator
value for the type
attribute. The
value of other
for the type
attribute is not yet supported.
href
attribute currently supports only the file
protocol,
i.e. files on the local machine. Therefore, values for the href
attribute must be of the form file://path/to/the/file
.
actuate
attribute is ignored for now, but it acts as
if the value onRequest
was in effect.
encoding
attribute currently supports only the value none
.
expires
and rights
attributes are currently ignored.
#PCDATA
content of the
element. In the future, the #PCDATA
content may be used to store
embedded data.
VOTABLE
object always has an underlying XML::DOM::Element
object. As long as the internal structure is manipulated only by the
publicly-available methods, this should be an adequate assumption. If
a method detects an aberrant case, a warning message is printed (using
the Carp::carp
subroutine), and the method fails.
XML::DOM
methods always
succeed. If a method detects an aberrant case, a warning message is
printed (using the Carp::carp
subroutine), and the method fails.
set_XXX
accessors do not perform validation of the
new attribute values. The exceptions are the accessors for attributes
with enumerated values; the new value is checked against the list of
acceptable values, as defined in the DTD.
VOTABLE
, VOTABLE::BINARY
, VOTABLE::FITS
Eric Winter, NASA GSFC (elwinter@milkyway.gsfc.nasa.gov)
$Id: STREAM.pm,v 1.1.1.15 2002/06/09 21:13:08 elwinter Exp $