view release on metacpan or  search on metacpan

lib/Business/cXML.pm  view on Meta::CPAN

=item B<log_callback>

Subroutine, passed to L</log_callback()>.

=item B<handlers>

Hash of handlers, dereferenced and passed to L</on()>.

=back

=cut

sub new {
	my ($class, %options) = @_;

	my $self = {
		local           => ($options{local} || ''),
		remote          => ($options{remote} || undef),
		secret          => ($options{secret} || undef),
		sender_callback => undef,
		log_level       => ($options{log_level} || CXML_LOG_NOTHING),
		log_callback    => ($options{log_callback} || \&_log_default),
		routes => {
			Profile => {
				__handler => \&_handle_profile,
			},
		},
	};
	bless $self, $class;
	$self->sender_callback($options{sender_callback}) if exists $options{sender_callback};
	$self->on(%{ $options{handlers} }) if exists $options{handlers};
	return $self;
}

sub _handle_profile {
	my ($self, $req, $res) = @_;

	$res->status(200);

	my $data = $res->xml_payload;

	$data->attr(effectiveDate => $res->timestamp);
	# UNIMPLEMENTED: lastRefresh?

	# UNIMPLEMENTED: service-level (outside Transaction blocks) options: service, attachments, changes, requestNames
	# Possibly also: Locale (found in an example, but not in any documentation)
	# There was no documentation about these in the cXML 1.2.036 PDF manual nor in the DTD comments.
	foreach my $route (keys (%{ $self->{routes} })) {
		my $tx = $data->add('Transaction', undef, requestName => ($route . 'Request'));
		$tx->add(URL => $self->{local});
		foreach my $opt (grep { $_ ne '__handler' } keys (%{ $self->{routes}{$route} })) {
			$tx->add('Option', $self->{routes}{$route}{$opt}, name => $opt);
		};
	};
}


=item C<B<sender_callback>( I<$sub> )>

By default, a request's From/Sender credentials are only used to guess
response credentials.  If you specify a callback here, it will be invoked
immediately after XML parsing, before passing to transaction handlers, giving
you an opportunity to authenticate the caller.

Your subroutine will be passed 3 arguments:

=over

=item 1. The current L<Business::cXML> object

=item 2. The Sender L<Business::cXML::Credential> object

=item 3. The From L<Business::cXML::Credential> object

=back

If you return a false value, the request will be deemed unauthorized and no
handler will be invoked.

If you return anything else, it will be stored and available in the request
sender's C<_note> property.  (See L<Business::cXML::Credential> for details.)

Note that cXML From/Sender headers contain information about an entire company
you're doing business with.  The identity of the specific person triggering
the request, if applicable, will be somewhere in contact or extrinsic data in
the payload itself.

=cut

sub sender_callback {
	my ($self, $callback) = @_;
	$self->{sender_callback} = $callback if ref($callback) eq 'CODE';
}

=item C<B<log_callback>( I<$sub> )>

By default, basic details about log-worthy events are dumped to C<STDERR>
(filtered according to the current log level).  By specifying your own
handler, you can do anything else you'd like when informative events occur.

Your subroutine will be passed 5 arguments:

=over

=item 1. The current L<Business::cXML> object

=item 2. The level

=over

=item CXML_LOG_ERR = 1 = fatal error (on our side)

=item CXML_LOG_WARN = 2 = warning (errors on the other end, network issues, etc.)

=item CXML_LOG_INFO = 3 = normal operations like receiving or sending transmissions

=item CXML_LOG_DEBUG = 4 = additional debugging information about processing requests

=item CXML_LOG_TRACE = 5 = full trace logging in some areas

=back