WSRF::Lite - Implementation of the Web Service Resource Framework
This document refers to version 0.8.3.3 of WSRF::Lite released July, 2018
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.
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.
Defines the set of namespaces used in WSRF::Lite and the directories used to store the named sockets and data files.
Directory to contain the named sockets of the process based WS-Resources.
Directory used to store files that hold state of WS-Resoures that use file based storage
WS-Addressing namespace.
WS-ResourceLifetimes namespace.
WS-ResourceProperties namespace.
WS-ServiceGroup namespace.
WS-BaseFaults namespace.
WS-Security untility namespace.
WS-Security extension namespace.
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.
Extends SOAP::SOM with one extra method "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;
Overrides SOAP::Deserializer to return a WSRF::SOM object, which includes the raw XML of the message, from the deserialize method.
The methods are the same as SOAP::Deserializer.
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.
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.
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]') );
All methods are the same as SOAP::Serializer except "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 handles incoming messages and dispatchs them to the appropriate WS-Resource.
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.
Class to provide support for WS-Addressing
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.
Creates a new WSRF::WS_Address object from a SOM representation of a SOAP Envelope that contains a WS-Addressing Endpoint Reference.
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.
Returns the WS-Addressing Endpoint Reference as a string.
Outputs the ReferenceParameters of the WS-Addressing Endpoint Reference.
Class to support the WSRF BaseFaults specification
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 provides two helper sub routines for converting a W3C time to seconds since the Epoch and vice versa.
Converts a W3C date time string to the number of seconds since the UNIX Epoch.
Converts a time in seconds since the UNIX Epoch to a W3C date time string.
You can specify how long until an item expires with $WSRF::TIME::EXPIRES_IN. This variable defaults to 60 seconds.
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.
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
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 returns the WSRF identifier for the WS-Resource.
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.
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);
This class provides support for serializing the state of a WS-Resource to a file.
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.
Returns the WSRF::Lite indentifier of the WS-Resource.
Filename of the file that holds the state of the WS-Resource.
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 provides one helper routine header
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); }
Provides support for WSRF ResourceProperties, the properties of the WS-Resource are stored in a hash called %WSRF::WSRP::ResourceProperties.
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.
If a WS-Resource module inherits from this class then its ResourceProperties will be stored in a file.
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.
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
Extends WSRF::MultiResourceProperties to add support for WS-ResourceLifetime.
Provides support for WS-ServiceGroups. This implementation of WS-ServiceGroups stores the state of the WS-ServiceGroup in a file, it extends WSRF::FileBasedResourceLifetimes.
Adds a WS-Resource to the ServiceGroup
Creates a new ServiceGroup
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.
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.
WSRF::Lite supports the same set of methods as SOAP::Lite with the addition of wsaddess.
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();
Provides support for digitally signing SOAP messages according to the WS-Security specification.
To install WSRF::Lite, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WSRF::Lite
CPAN shell
perl -MCPAN -e shell install WSRF::Lite
For more information on module installation, please visit the detailed CPAN module installation guide.