File Coverage

blib/lib/Net/SDEE.pm

Criterion	Covered	Total	%
statement	13	15	86.6
branch			n/a
condition			n/a
subroutine	5	5	100.0
pod			n/a
total	18	20	90.0

# Net::SDEE.pm
#
# $Id: SDEE.pm,v 1.4 2005/03/07 20:12:39 jminieri Exp $
#
# Copyright (c) 2004-2005 Joe Minieri  and OpenService (www.open.com).
# All rights reserved.
# This program is free software; you can redistribute it and/or modify it under the same
# terms as Perl itself.
#

package Net::SDEE;

use 5.006001;
use strict;
use warnings;

use LWP::UserAgent;

use XML::SDEE;
use Net::SDEE::Query;
use Net::SDEE::Session;
use Net::SDEE::Subscription;

our $VERSION = '0.01';

#
# These are the parameters for each query type
my @_open_parameters = qw/action sessionId startTime events idsAlertSeverities force/;
my @_get_parameters = qw/action sessionId subscriptionId timeout maxNbrOfEvents confirm/;
my @_cancel_parameters = qw/action sessionId subscriptionId/;
my @_close_parameters = qw/action sessionId subscriptionId/;

##########################################################################################
#
# AUTOLOAD get/set methods when they're generic
#
use vars '$AUTOLOAD';
sub AUTOLOAD {
        no strict 'refs';
        my ($self, $value) = @_;

        my $method =($AUTOLOAD =~ /.*::([_\w]+)$/)[0];
        return if $method eq 'DESTROY';

	#
	# Pass all unknown methods to the session object
        unless(defined($method) and exists($self->{ _session }->{ $method })) {
                $self->call_debug("No such parameter $method");
                return undef;
        }

        # set this up for next time
        *{$AUTOLOAD} = sub {
                my ($self, $value) = @_;
                if (defined($value)) {
                        return $self->{ _session }->{ $method } = $value;
                } else {
                        return defined($self->{ _session }->{ $method })?$self->{ _session }->{ $method }:undef;
                }
        };

        goto &$AUTOLOAD;
}
#
##########################################################################################

##########################################################################################
#
# Debug callback routine
#
sub debug_log {
	my $message = shift;

	unless(defined($message)) { return undef }

	# caller 0 = current
	# caller 1 = eval
	# caller 2 = call_debug
	# caller 3 = actual caller
	my $caller = (caller(3))[3];
	print "$caller() $message\n";
	#warn $message;
}

sub debug_callback {
	my ($self, $callback) = @_;

	unless(defined($callback)) {
		return $self->{ _debug_callback };
	}

	$self->set_callback('_debug_callback', $callback);
}

sub call_debug {
	my $self = shift;

	return unless(defined($self->{ _debug_callback }));

	if(defined($self->debug)) {
		my $handler = $self->{ _debug_callback };
		my $ret = eval { &$handler(@_); };

		return (defined($ret))?$ret:$@;
	} else {
		return undef;
	}
}

sub debug {
	my ($self, $debug) = @_;

	if(defined($debug)) {
		return $self->{ _debug } = $debug;
	} else {
		return $self->{ _debug };
	}
}

#
##########################################################################################

##########################################################################################
#
# Callback setting/executing methods
#
sub execute {
	my $self = shift;

	return unless(defined($self->{ _callback }));

	my $handler = $self->{ _callback };
	my $ret = eval {
		# block out die/warn just in case...
		local $SIG{ __DIE__ };
		local $SIG{ __WARN__ };
		&$handler(@_);
	};

	return (defined($ret))?$ret:$@;
}

sub set_callback {
	my ($self, $which, $callback) = @_;

	unless(defined($callback) and defined($which)) {
		return $self->{ $which };
	}

	if(ref($callback) eq 'CODE') {
		$self->{ $which } = $callback;
	} else {
		return undef;
	}
}

sub callback {
	my ($self, $callback) = @_;

	unless(defined($callback)) {
		return $self->{ _callback };
	}

	$self->set_callback('_callback', $callback);
}

sub returnResults {
	my $self = shift;
	my $results = shift;

	if(defined($self->returnRawXML)) {
		# return RAW XML only
		return defined($self->callback)?$self->execute($results, @_):$results;
	}

	my $returnContents;
	unless(defined($self->{ _xml }->XML)) {
		$self->{ _xml }->consume($results);
		if($self->{ _xml }->isError) {
			$self->call_debug( $self->{ _xml }->getErrorString );
		}
	}

	if(defined($self->returnXML)) {
		# return PROCESSED XML only
		$returnContents = $self->{ _xml }->SDEE;
		return defined($self->callback)?$self->execute($returnContents, @_):$returnContents;
	}

	# return only events
	if(defined($self->callback)) {
		# execute "callback" for each event
		my @returnValues;
		while(my $event = $self->{ _xml }->getEvent) {
			my $ret = $self->execute($event, @_);
			push(@returnValues, $ret);
		}
		return \@returnValues;
	} else {
		$returnContents = $self->{ _xml }->getEvents;
		return defined($self->callback)?$self->execute($returnContents, @_):$returnContents;
	}
}
#
##########################################################################################

##########################################################################################
#
# set/get methods
#
sub returnRawXML {
	my ($self, $returnRawXML) = @_;

	if(defined($returnRawXML)) {
		return $self->{ _returnRawXML } = $returnRawXML;
	} else {
		return $self->{ _returnRawXML };
	}
}

sub returnXML {
	my ($self, $returnXML) = @_;

	if(defined($returnXML)) {
		return $self->{ _returnXML } = $returnXML;
	} else {
		return $self->{ _returnXML };
	}
}

sub returnEvents {
	my ($self, $returnEvents) = @_;

	if(defined($returnEvents)) {
		return $self->{ _returnEvents } = $returnEvents;
	} else {
		return $self->{ _returnEvents };
	}
}
#
##########################################################################################

##########################################################################################
#
sub getNumberOfSubscriptions {
	my $self = shift;

	return scalar keys %{$self->{ _subscriptions }};
}

sub getSubscription {
	my ($self, $subscriptionId) = @_;

	unless(defined($subscriptionId) and exists($self->{ _subscriptions }->{ $subscriptionId })) { return undef }

	return $self->{ _subscriptions }->{ $subscriptionId };
}

sub getSubscriptionIds {
	my $self = shift;

	my @returnValue = keys %{$self->{ _subscriptions }};
	return \@returnValue;
}

sub addSubscription {
	my $self = shift;

	if( $#_ == 0 and ref($_[0]) eq 'Net::SDEE::Subscription') {
		return $self->open($_[0]);
	} else {
		return $self->open(Net::SDEE::Subscription->new(@_));
	}
}

sub deleteSubscription {
	my ($self, $subscriptionId) = @_;

	unless(defined($subscriptionId) and exists($self->{ _subscriptions }->{ $subscriptionId })) { return undef }

	return delete($self->{ _subscriptions }->{ $subscriptionId });
}

sub addQuery {
	my $self = shift;

	if( $#_ == 0 and ref($_[0]) eq 'Net::SDEE::Query') {
		$self->{ _query } = $_[0];
	} else {
		$self->{ _query } = Net::SDEE::Query->new(@_);
	}
}

sub addSession {
	my $self = shift;

	if( $#_ == 0 and ref($_[0]) eq 'Net::SDEE::Session') {
		$self->{ _session } = $_[0];
	} else {
		$self->{ _session } = Net::SDEE::Session->new(@_);
	}
}
#
##########################################################################################

##########################################################################################
#
sub new {
        my $caller = shift;
        my %args = @_;

	my $class = (ref($caller) or $caller);
        my $self = bless {
			'_xml',			XML::SDEE->new(),
			'_session',		undef,
			'_subscriptions',	{},
			'_query',		undef,
			'_callback',		undef,
			'_returnXML',		undef,
			'_returnRawXML',	undef,
			'_returnEvents',	undef,
			'_debug',		undef,
			'_debug_callback',	\&debug_log
		}, $class;

	if(defined($args{ Session }) and ref($args{ Session }) eq 'Net::SDEE::Session') {
		$self->{ _session } = $args{ Session };
		delete($args{ Session }); # clean up for loop @ bottom
	} else {
		$self->{ _session } = Net::SDEE::Session->new();
	}

	if(defined($args{ Query }) and ref($args{ Query }) eq 'Net::SDEE::Query') {
		$self->{ _query } = $args{ Query };
		delete($args{ Query }); # clean up for loop @ bottom

		# we should NOT have both, so drop the subscription if we do...
		delete($args{ Subscription });
	}

	#
	# Note, we cannot pass in a Subscription because we need an Subscription ID that
	# we only get when we connect.
	#
	foreach my $attribute ( keys %args ) {
		$self->$attribute( $args{ $attribute });
	}

	#
	# If we've set 'returnXML', then make sure 'returnEvents' is unset.
	# Also, if 'returnXML' is not set, make sure 'returnEvents' is set.
	if(defined($self->returnRawXML)) {
		# return RAW XML
		$self->returnXML(undef);
		$self->returnEvents(undef);
	} elsif(defined($self->returnXML)) {
		# return PROCESSED XML
		$self->returnRawXML(undef);
		$self->returnEvents(undef);
	} else {
		# return Events
		$self->returnXML(undef);
		$self->returnRawXML(undef);
		$self->returnEvents(1);
	}

        return $self;
}

#
# Opens a session
# Parameters:
# - action = open
# - startTime = 0
# - events = evtype
# - idsAlertSeverities
# - force = yes/no
#
# Response Code:
# - errLimitExceeded = server has reached subscription limit
#
# Return subscriptionID
#
sub open {
	my $self = shift;

	my $subscription = undef;
	if(defined($_[0]) and ref($_[0]) eq 'Net::SDEE::Subscription') {
		# got a subscription object
		$subscription = shift;
	} else {
		# don't have a subscription object, make a new one
		$subscription = Net::SDEE::Subscription->new();
	}

	unless(defined($subscription->sessionId)) {
		if(my $sessionId = $self->{ _session }->sessionId) {
			$subscription->sessionId($sessionId);
		}
	}

	if( $#_ > 0 ) {
		my %args = @_;
		foreach my $parameter (keys %args) {
			$subscription->$parameter($args{ $parameter });
		}
	}

	$subscription->action('open');

        my $LWP = LWP::UserAgent->new();
        my $result = $LWP->post(
		$self->{ _session }->getURL,
                $subscription->getParameters(@_open_parameters),
                %{ $self->{ _session }->getHeader }
	);

	if($result->is_success) {
		if($self->{ _session }->Type eq 'subscription') {
			if(my $cookie = $result->headers('SET-COOKIE')) {
				$self->{ _session }->Cookie((split(';', $cookie))[0]);
			} else {
				$self->call_debug( 'No Cookie in header: ' . $result->status_line);
				return undef;
			}
			$self->{ _session }->state('opened');
		}

		$self->{ _xml }->reset;
		$self->{ _xml }->consume($result->content);
		if(my $sessionId = $self->{ _xml }->sessionId) {
			$self->sessionId($sessionId);
			$subscription->sessionId($sessionId);
			$self->call_debug("New SessionID: $sessionId");
		} elsif($sessionId = $self->{ _session }->sessionId) {
			$self->call_debug("Existing SessionID: $sessionId");
		} else {
			$self->call_debug('NO SessionID');
		}
		if(my $subscriptionId = $self->{ _xml }->subscriptionId) {
			$subscription->subscriptionId($subscriptionId);
			$self->{ _subscriptions }->{ $subscriptionId } = $subscription;
			$self->call_debug("New SubscriptionID: $subscriptionId");
		}
	} else {
		$self->call_debug( 'open failed: ' . $result->status_line);
		return undef;
	}
	return $self->returnResults($result->content, $subscription->subscriptionId);
}

#
# Retrieve Events
# Parameters:
# - action = get
# - timeout = # (blocking, waiting for events )
# - maxNbrOfEvents = #
# - confirm = yes/no
#   * unconfirmed events will be resent
#
# Response Codes:
# - missedEvents - server dropped events since last retrieval
# - errNotFound - subscription not open
# - errInUse - retrieval already taking place
#
sub get {
	my ($self, $subscriptionId) = @_;

	my $parameters;
	if(defined($subscriptionId)) {
		# setup for subscription

		# perhaps should call open() to fix these? but what to do w/ returned XML?
		unless(defined($self->{ _subscriptions }->{ $subscriptionId })) {
			$self->call_debug("No such subscription Id: $subscriptionId");
			return undef;
		}
        	unless( $self->{ _session }->state eq 'opened' ) {
			$self->call_debug('Session state is ' . $self->{ _session }->state);
			return undef;
		}
		$self->{ _subscriptions }->{ $subscriptionId }->action('get');
                $parameters = $self->{ _subscriptions }->{ $subscriptionId }->getParameters(@_get_parameters);
	} else {
		# setup for query
		unless(defined($self->{ _query })) {
			$self->{ _query } = Net::SDEE::Query->new();
		}
                $parameters = $self->{ _query }->getParameters(@_get_parameters);
	}

        my $LWP = LWP::UserAgent->new();
        my $result = $LWP->post(
		$self->{ _session }->getURL,
		$parameters,
                %{ $self->{ _session }->getHeader }
	);

        if($result->is_success) {
		#
		# Response Codes:
		# - missedEvents - server dropped events since last retrieval
		# - errNotFound - subscription not open
		# - errInUse - retrieval already taking place
		#
        } else {
                $self->call_debug('http session failed ' . $result->status_line);
                $self->{ _session }->state('closed');
		return undef;
        }
	$self->{ _xml }->reset;
	return $self->returnResults($result->content, $subscriptionId);
}

#
# Cancels a blocked subscription
#
# Parameters:
# - action = cancel
#
# Response Codes:
# - errNotFound - subscription not open
#
# Return ?? XML document?
#
sub cancel {
	my ($self, $subscriptionId) = @_;

	return undef unless(defined($subscriptionId));

	$self->call_debug("SubscriptionId: $subscriptionId");

	my $subscription;
	unless($subscription = $self->getSubscription( $subscriptionId )) {
		$self->call_debug("NO subscription $subscriptionId");
		return undef;
	}

	$subscription->action('cancel');

        my $LWP = LWP::UserAgent->new();
        my $result = $LWP->post(
		$self->{ _session }->getURL,
                $subscription->getParameters(@_cancel_parameters),
                %{ $self->{ _session }->getHeader }
	);

        if($result->is_success) {
		#
		# Response Codes:
		# - errNotFound - subscription not open
		#
        } else {
                $self->call_debug( 'cancel failed: ' . $result->status_line);
		return undef;
        }
	$self->{ _xml }->reset;
	return $self->returnResults($result->content, $subscriptionId);
}

#
# Closes a subscription
#
# Parameters:
# - action = close
#
# Response Codes:
# - errNotFound - subscription not open
#
# Return ?? XML document?
#
sub close {
	my ($self, $subscriptionId) = @_;

	return undef unless(defined($subscriptionId));

	my $subscription;
	unless($subscription = $self->getSubscription( $subscriptionId )) {
		$self->call_debug("NO subscription $subscriptionId");
		return undef;
	}

	my $sessionId = $subscription->sessionId;
	$self->call_debug("SessionId: $sessionId, SubscriptionId: $subscriptionId");

	$subscription->action('close');

        my $LWP = LWP::UserAgent->new();
        my $result = $LWP->post(
		$self->{ _session }->getURL,
                $subscription->getParameters(@_close_parameters),
                %{ $self->{ _session }->getHeader }
	);

	$self->deleteSubscription($subscriptionId);
        if($result->is_success) {
		#
		# Response Codes:
		# - errNotFound - subscription not open
		#
        } else {
                $self->call_debug( 'close failed: ' . $result->status_line);
		return undef;
        }
	$self->{ _xml }->reset;
	return $self->returnResults($result->content, $subscriptionId);
}

#
# get ALL
sub getAll {
	my $self = shift;

	my $returnAll = {};

	foreach my $subscriptionId ( @{ $self->getSubscriptionIds } ) {
		if(my $return_value =$self->get($subscriptionId)) {
			$self->call_debug($return_value);
		}
	}

	return $returnAll;
}

#
# close ALL
sub closeAll {
	my $self = shift;

	my $returnAll = {};

	# need to close ALL the subscriptions
	foreach my $subscriptionId ( @{ $self->getSubscriptionIds }) {
		if(my $return_value =$self->close($subscriptionId)) {
			$self->call_debug($return_value);
		}
	}

	return $returnAll;
}

#
# Close the session, just in case we forgot...
sub DESTROY {
	my $self = shift;

	# need to close ALL the subscriptions
	$self->closeAll();
}

#
##########################################################################################

1;
__END__