/ 
WSRF-Lite-0.8.3.4
River stage one • 3 direct dependents • 3 total dependents
/ WSRF::Lite

NAME

WSRF::Lite - Implementation of the Web Service Resource Framework

VERSION

This document refers to version 0.8.3.3 of WSRF::Lite released July, 2018

SYNOPSIS

This is an implementation of the Web Service Resource Framework (WSRF), which is built on SOAP::Lite. It provides support for WSRF, WS-Addressing and for digitally signing a SOAP messages using an X.509 certificate according to the OASIS WS-Security standard.

DESCRIPTION

WSRF::Lite consists of a number of classes for developing WS-Resources. A WS-Resource is an entity that has a Web service interface defined by the WSRF family of specifications that maintains state between calls to the service.

WSRF::Lite provides a number of ways of implementing WS-Resources: one approach uses a process to store the state of the WS-Resource, another approach uses a process to store the state of many WS-Resources and the last approach uses files to store the state of the WS-Resources between calls to the WS-Resource. The different approachs have different benifits, using one process per WS-Resource does not scale very well and isn't very fault tolerant (eg a machine reboot) but is quite easy to develop. The approachs are just examples of how to implement a WS-Resource, it should be possible to use them as a basis to develop tailored solutions for particular applications. For example you could use a relational database to store the state of the WS-Resources.

WSRF::Constants

Defines the set of namespaces used in WSRF::Lite and the directories used to store the named sockets and data files.

$WSRF::Constants::SOCKETS_DIRECTORY

Directory to contain the named sockets of the process based WS-Resources.

$WSRF::Constants::Data

Directory used to store files that hold state of WS-Resoures that use file based storage

$WSRF::Constants::WSA

WS-Addressing namespace.

$WSRF::Constants::WSRL

WS-ResourceLifetimes namespace.

$WSRF::Constants::WSRP

WS-ResourceProperties namespace.

$WSRF::Constants::WSSG

WS-ServiceGroup namespace.

$WSRF::Constants::WSBF

WS-BaseFaults namespace.

$WSRF::Constants::WSU

WS-Security untility namespace.

$WSRF::Constants::WSSE

WS-Security extension namespace.

$WSRF::Constants::WSA_ANON

From the WS-Addressing specification, it is used to indicate an anonymous return address. If you are using a request-response protocol like HTTP which uses the same connection for the request and response you use this as the ReplyTo address in SOAP WS-Addressing header of the request.

WSRF::SOM

Extends SOAP::SOM with one extra method "raw_xml".

METHODS

raw_xml

Returns the raw XML of a message, useful if you want to parse the message using some other tool than provided with SOAP::Lite:

my $xml = $som->raw_xml;

WSRF::Deserializer

Overrides SOAP::Deserializer to return a WSRF::SOM object, which includes the raw XML of the message, from the deserialize method.

METHODS

The methods are the same as SOAP::Deserializer.

WSRF::WSRFSerializer

Overrides SOAP::Serializer. This class extends the SOAP::Serializer class which creates the XML SOAP Enevlope. WSRF::WSRFSerializer overrides the "envelope" method so that it adds the WSRF, WS-Addressing and WS-Security namespaces to the SOAP Envelope, it also where the message signing happens. The XML SOAP message has to be created before it can be signed.

METHODS

The methods are the same as SOAP::Serializer, the "envelope" method is overridden to include the extra namespaces and to digitally sign the SOAP message if required.

WSRF::SimpleSerializer

Overrides SOAP::Serializer. This is helper class that is based in SOAP::Serializer, it will serialize a SOAP::Data object into XML but without adding the SOAP namespaces etc. It is useful if you want to extra some simple XML from a SOM object, retrieve a SOAP::Data object from the SOM then serialize it to simple XML.

my $serializer = WSRF::SimpleSerializer->new();
my $xml = $seriaizer->serialize( $som->dataof('/Envelope/Body/[1]') );

METHODS

All methods are the same as SOAP::Serializer except "serialize".

serialize

This method from SOAP::Serializer is overridden so that it does not add the SOAP namepaces to the XML or set the types of the elements in the XML.

sub serialize {
   my $self = shift @_;
   $self->autotype(0);
   $self->namespaces({});
   $self->encoding(undef);
   $self->SUPER::serialize(@_);
}

WSRF::Container

WSRF::Container handles incoming messages and dispatchs them to the appropriate WS-Resource.

METHODS

handle

Takes a HTTP Request object and dispatchs it to the appropriate WS-Resource, handle returns a HTTP Response object from the WS-Resource which should be returned to the client.

WSRF::WS_Address

Class to provide support for WS-Addressing

METHODS

new

Creates a new WSRF::WS_Address object, takes either a SOM object or raw XML that contains a WS-Addressing Endpoint Reference and creates a WSRF::WS_Addressing object.

from_envelope

Creates a new WSRF::WS_Address object from a SOM representation of a SOAP Envelope that contains a WS-Addressing Endpoint Reference.

MessageID

If the WSRF::WS_Address is used to send a message to a service to client this function is used to create a unique identifier for the message. The identifier goes into the WS-Addressing SOAP Header MessageID.

XML

Returns the WS-Addressing Endpoint Reference as a string.

serializeReferenceParameters

Outputs the ReferenceParameters of the WS-Addressing Endpoint Reference.

WSRF::BaseFaults

Class to support the WSRF BaseFaults specification

METHODS

die_with_Fault

To return a WSRF BaseFault call die_with_Fault. die_with_Fault creates a SOAP fault then dies.

die_with_Fault(
   OriginatorReference => $EPR,             
   ErrorCode           => $errorcode,     
   dialect             => $dialect,       	
   Description         => $Description,
   FaultCause          => $FaultCause  
 );

OriginatorReference is the WS-Addressing Endpoint Reference of the WS-Resource that the fault orignially came from. ErrorCode allows the WS-Resource to pass an error code back to the client. dialect is the dialect that the error code belongs to. Description provides a description of the fault and FaultCause provides the reason for the fault.

WSRF::Time

WSRF::Time provides two helper sub routines for converting a W3C time to seconds since the Epoch and vice versa.

METHODS

ConvertStringToEpochTime

Converts a W3C date time string to the number of seconds since the UNIX Epoch.

ConvertEpochTimeToString

Converts a time in seconds since the UNIX Epoch to a W3C date time string.

VARIABLES

EXPIRES_IN

You can specify how long until an item expires with $WSRF::TIME::EXPIRES_IN. This variable defaults to 60 seconds.

WSRF::Resource

A process based WS-Resource. The state of the WS-Resource is held in a process, the WSRF::Lite Container talks to the WS-Resource via a named UNIX socket.

METHODS

new

Creates a new WSRF::Resource.

  my $resource = WSRF::Resource->new(
          module    => Counter,       
          path      => /WSRF/Counter/Counter.pm,
	  ID        => M4325324563456,
	  namespace => Counter
          );

module is the name of the module that implements the WS-Resource, path is the path to the module relative to $ENV{WSRF_MODULES}, ID is the identifier for your WS-Resource, it will used as part of the URI in the WS-Addressing EPR. If you do not include the ID one will be assigned for you. namespace is the namespace of the WSDL port for any non WSRF operations the WS-Resource supports, if no namespace is provided the name of the module will be used

handle

This subroutine should be called after new. It forks the process that is the WS-Resource. Anything passed to handle is sent to the init method of the WS-Resource after it is created. The WS-Addressing EPR of the WS-Resource is available to the WS-Resource through $ENV{WSA}. handle returns the WSRF identifier for the WS-Resource, this is used to form the URI used in the WS-Addressing EPR.

ID

ID returns the WSRF identifier for the WS-Resource.

WSRF::FileLock

Simple class to provide file locking. It is possible to use fcntl to do file locking but some file systems don't support it. WSRF::FileLock is used to by the file based WS-Resources in WSRF::Lite to prevent concurrent access to the WS-Resource by more than one client.

METHODS

new

new takes a name and tries to create a directory with that name, if there is already a directory with that name it will sleep for half a second and retry. When the directory is created a new WSRF::FileLock object is returned, then the object goes out of scope the directory is removed.

my $lock = WSRF::FileLock->new($somefilelocation);

WSRF::File

This class provides support for serializing the state of a WS-Resource to a file.

METHODS

new

Takes a WSRF::SOM envelope, gets the ID of the WS-Resource and then loads the properties of the WS-Resource into the WSRF::WSRP::ResourceProperties hash. new locks the WS-Resource so that no other client can access the WS-Resource while this clients request is being processed. When the WSRF::File object runs out of scope and is destroyed the lock is removed.

ID

Returns the WSRF::Lite indentifier of the WS-Resource.

path

Filename of the file that holds the state of the WS-Resource.

toFile

Serializes the WSRF::WSRP::ResourceProperties hash back to the file. If the properties of the WS-Resource have been modified this should be called before the WSRF::File object goes out of scope.

WSRF::Header

WSRF::Header provides one helper routine header

METHODS

This subroutine takes a WSRF::SOM envelope and creates the appropriate SOAP Headers for the response including the required WS-Addressing SOAP headers.

sub foo {
   my $envelope = pop @_;
   
   return WSRF::Header::header($envelope); 
 }

WSRF::WSRP

Provides support for WSRF ResourceProperties, the properties of the WS-Resource are stored in a hash called %WSRF::WSRP::ResourceProperties.

METHODS

xmlizeProperties
GetResourcePropertyDocument
GetResourceProperty
GetMultipleResourceProperties
SetResourceProperties
InsertResourceProperties
UpdateResourceProperties
DeleteResourceProperties

WSRF::WSRL

Provides support for WS-ResourceLifetimes. WS-ResourceLifetime defines a standard mechanism for controlling the lifetime of a WS-Resource. It adds the ResourceProperty TerminationTime to the set of ResourceProerties of the WS-Resource, the TerminationTim cannot be changed through the WS-ResourceProperties - it can only be modified using the WS-ResourceLifetime SetTerminationTime operation.

METHODS

Destroy
SetTerminationTime

WSRF::FileBasedResourceProperties

If a WS-Resource module inherits from this class then its ResourceProperties will be stored in a file.

METHODS

GetResourceProperty
GetMultipleResourceProperties
SetResourceProperties
InsertResourceProperties
UpdateResourceProperties
DeleteResourceProperties
GetResourcePropertyDocument

WSRF::FileBasedResourceLifetimes

If a WS-Resource wants to store its state in a file and wants to support WS-ResourceLifetimes it should inherit from this class. WSRF::FileBasedResourceLifetimes inherits from WSRF::FileBasedResourceProperties.

METHODS

Destroy
SetTerminationTime

WSRF::MultiResourceProperties

In this case a single process acts on behave of a number of WS-Resources. The ResourceProperties are all held in a hash - the WSRF::Lite identifier of the WS-Resource is used as the key to the hash. The WSRF::Lite Container talks to the process through a named UNIX socket - the name of the socket is the same as the name of the module. The WS-Resource module should inherit this class

METHODS

GetResourcePropertyDocument
GetResourceProperty
GetMultipleResourceProperties
SetResourceProperties
InsertResourceProperties
UpdateResourceProperties
DeleteResourceProperties

WSRF::MultiResourceLifetimes

Extends WSRF::MultiResourceProperties to add support for WS-ResourceLifetime.

METHODS

Destroy
SetTerminationTime

WSRF::ServiceGroup

Provides support for WS-ServiceGroups. This implementation of WS-ServiceGroups stores the state of the WS-ServiceGroup in a file, it extends WSRF::FileBasedResourceLifetimes.

METHODS

Add

Adds a WS-Resource to the ServiceGroup

createServiceGroup

Creates a new ServiceGroup

WSRF::ServiceGroupEntry

Provides support for ServiceGroupEntry WS-Resources defined in the WS-ServiceGroup specification. Each ServiceGroupEntry WS-Resource represents an entry in a ServiceGroup, destroy the ServiceGroupEntry and the entry disappears from the ServiceGroup.

METHODS

GetResourcePropertyDocument
GetResourceProperty
GetMultipleResourceProperties
SetResourceProperties
Destroy
SetTerminationTime

WSRF::Lite

Extends SOAP::Lite to provide support for WS-Addressing. WSRF::Lite uses WSRF::WSRFSerializer and WSRF::Deserializer by default, it will also automatically include the WS-Addressing SOAP headers in the SOAP message. If $ENV{WSS} is set to true, $ENV{HTTPS_CERT_FILE} points to the public part of a X.509 certificate and $ENV{HTTPS_KEY_FILE} points to the unencrypted private key of the certificate then WSRF::Lite will digitally sign the message according to the WS-Security specification.

METHODS

WSRF::Lite supports the same set of methods as SOAP::Lite with the addition of wsaddess.

wsaddress

This can be used instead of the proxy method, it takes a WSRF::WS_Address object for the address of the service or WS-Resource:

$ans=  WSRF::Lite
  -> uri($uri)
  -> wsaddress(WSRF::WS_Address->new()->Address($target))              
  -> createCounterResource();

WSRF::WSS

Provides support for digitally signing SOAP messages according to the WS-Security specification.

METHODS

sign
verify