NAME

LS::SOAP::Service - SOAP service for LSID authority, metadata, and data operations

SYNOPSIS

#!/usr/bin/perl

# This is a CGI script

use LS::SOAP::Service transport => 'HTTP::CGI'

LS::SOAP::Service
	-> dispatch_authority_to('AuthorityService')
	-> dispatch_metadata_to('MetadataService')
	-> dispatch_data_to('DataService')
	-> handle;


package AuthorityService;


sub getAvailableServices {
	my $self = shift;
	my ($lsid_string) = @_;

	return "<wsdl></wsdl>";
}


package MetadataService;

sub getMetadata {
	return 'This is the metadata';
}


package DataService;

sub getData {
	my $self = shift;
	my ($lsid) = @_;
	
	my $data = "";

	return $data;
}

DESCRIPTION

An object of the LS::SOAP::Service class is used to implement an LSID authority service, metadata service, or data service. LS::SOAP::Service is a subclass of SOAP::Server, and generates and accepts SOAP messages which are formatted differently than those which are generated and accepted by SOAP::Server.

An authority service must implement three methods: getAuthorityVersion, getKnownURIs, and getAvailableOperations, as defined at http://i3c.org/workgroups/technical_architecture/resources/lsid/docs/LSIDResolution.htm.

A metadata service must implement the getMetadata method.

A data service must implement the getData method.

A web service may either be an authority service, a metadata service, a data service, or any combination of the three.

More information on LSIDs and authorities can be found at http://i3c.org/workgroups/technical_architecture/resources/lsid/docs/index.htm.

METHODS

The superclass of LS::SOAP::Service is determined by the transport parameter specified in the use statement. If no transport parameter is specified, the superclass is SOAP::Server. Otherwise, the superclass is SOAP::Transport::{transport}. LS::SOAP::Service objects support the methods of their superclass, and these additional methods:

dispatch_authority_to ( $package_or_object )

This method is similar to the dispatch_to method on SOAP::Service, except that it only applies to the three required authority service methods: getAuthorityVersion, getKnownURIs, and getAvailableOperations. Incoming messages containing calls to these methods will be dispatched to the supplied package name or object instance. For backward compatibility, a the SOAP method getAvailableMethods will be treated as a synonym of getAvailableOperations. Either call will be dispatched to the implementation function getAvailableOperations, if it is defined. Otherwise, they will be dispatched to the implementation function getAvailableMethods.

getAvailableServices should return a WSDL string describing the operations available for the given LSID, which is passed in as a string. It may also return an object of type LS::SOAP::Response.

dispatch_metadata_to ( $package_or_object )

This method is similar to the dispatch_to method on SOAP::Service, except that it only applies to the metadata service method: getMetadata. Incoming messages containing a calls this method will be dispatched to the supplied package name or object instance.

getMetadata should return the metadata for the given LSID, as a Base64 encoded string. It may also return an object of type LS::SOAP::Response. The LSID is passed in as a string.

dispatch_data_to ( $package_or_object )

This method is similar to the dispatch_to method on SOAP::Service, except that it only applies to the data service method getData. Incoming messages containing a calls this method will be dispatched to the supplied package name or object instance.

getData should return the data for the given LSID, as a Base64 encoded string. The LSID is passed in as a string.

FAULTS

The LS::SOAP::FAULT class is provided to aid in creating SOAP faults. In addition to the methods of SOAP::Fault, LS::SOAP Fault provides get/set methods for an errorcode number and description string, which are placed in the fault details.

errorcode ( $num )

Sets or retrieves the numeric errorcode of the error.

description ( $desc_string )

Sets or retrieves a detailed, human readable description of the error.

Examples:

 sub getAvailablesServices {
 	my $self = shift;
 	my ($lsid_string) = @_;

	if (!known(LS::ID->new($lsid_string))) {
	 	die LS::SOAP::Fault->faultcode('Client')
		                   ->faultstring('Unknown LSID')
		                   ->errorcode(201)
		                   ->description(
		                   	'The LSID ' . 
		                   	$lsid_string . 
		                   	' is not known to this authority.'
		                     );
	}

	return "<wsdl></wsdl>";
 }

COMPLEX RESPONSES WITH LS::SOAP::Response

Some methods allow you to return an object of type LS::SOAP::Response. This enables you to return additional information in the header of the SOAP response. LS::SOAP::Response provides get/set methods for the return value and the expiration time of the response.

value ( $val )

Sets or retrieves the return value of the method call.

expires ( $date_time )

Sets or retrieves the expiration time of the result. This value may be used by caching clients. The time should be in ISO8601 format, as specified in the XML Schema specification, part 2 (http://www.w3.org/TR/xmlschema-2/#dateTime).

SEE ALSO

LS::Authority::WSDL::Simple

COPYRIGHT

Copyright (c) 2002,2003 IBM Corporation. All rights reserved. This program and the accompanying materials are made available under the terms of the Common Public License v1.0 which accompanies this distribution, and is available at http://www.opensource.org/licenses/cpl.php