cXML/Transmission.pm

filter: Statementstmt 16.4% 36 / 219 Branchbran 0.0% 0 / 102 Conditioncond 0.0% 0 / 19 MC/DCmcdc 0.0% 0 / 11 Subroutinesub 34.2% 12 / 35 Podpod 100% 21 / 21 totaltotal 16.9% 69 / 407 CC 61 SCAR 45.4
CC
61
Cov
11%
toString
342.0
_new_payload
132.0
new
80.5
CRAP 93.6
« cXML/ItemIn.pm ↑ Summary cXML.pm »
1 =encoding utf-8
2  
3 =head1 NAME
4  
5 Business::cXML::Transmission - cXML transmission
6  
7 =head1 SYNOPSIS
8  
9 use Business::cXML::Transmission;
10 $msg = parse Business::cXML::Transmission $incoming_cxml_string;
11  
12 =head1 DESCRIPTION
13  
14 Parser and compiler for cXML transmissions.
15  
16 See: L<http://xml.cxml.org/current/cXMLUsersGuide.pdf>
17  
18 The creation of these transmissions should normally be left to
19 L<Business::cXML>, which does some handy initialization for you. Of main
20 concern for manual processing is our L</payload()>.
21  
22 =cut
23  
24 7 ▶use 5.014;
Subroutine BEGIN: called CC=1 SCAR=0.0
25 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
26  
27 package Business::cXML::Transmission;
28  
29 7 ▶use Business::cXML::Credential;
Subroutine BEGIN: called CC=1 SCAR=0.0
30 7 ▶use Business::cXML::Utils qw(current_datetime cxml_timestamp);
Subroutine BEGIN: called CC=1 SCAR=0.0
31 7 ▶use XML::LibXML;
Subroutine BEGIN: called CC=1 SCAR=0.0
32 7 ▶use Clone qw(clone);
Subroutine BEGIN: called CC=1 SCAR=0.0
33 7 ▶use DateTime;
Subroutine BEGIN: called CC=1 SCAR=0.0
34 7 ▶use HTML::Entities;
Subroutine BEGIN: called CC=1 SCAR=0.0
35 7 ▶use MIME::Base64;
Subroutine BEGIN: called CC=1 SCAR=0.0
36 7 ▶use Sys::Hostname;
Subroutine BEGIN: called CC=1 SCAR=0.0
37  
38 7 ▶use constant {
Subroutine BEGIN: called CC=1 SCAR=0.0
39 7 CXML_CLASS_MESSAGE => 1,
40 CXML_CLASS_REQUEST => 2,
41 CXML_CLASS_RESPONSE => 3,
42 7 };
43  
44 =head1 METHODS
45  
46 =over
47  
48 =item C<B<new>( [I<$input>] )>
49  
50 Without I<C<$input>>, returns an empty L<Business::cXML::Transmission> ready
51 to be populated.
52  
53 With I<C<$input>>, returns a L<Business::cXML::Transmission> if parsing was
54 possible, or an arrayref with two elements if there was an error. The first
55 element is a status code, and the second contains a string with more details,
56 if available. Input is expected to be a full XML document string, optionally
57 encoded in Base64 (i.e. the contents of a C<cxml-base64> form variable).
58  
59 Possible codes:
60  
61 =over
62  
63 =item C<406>
64  
65 The input XML is invalid
66  
67 =item C<400>
68  
69 The input XML is valid, but the cXML structure is incomprehensible
70  
71 =back
72  
73 =cut
74  
75 10 ▶sub new {
Subroutine new: called CC=9 SCAR=43.9
Pod documented
76 10 my ($class, $input) = @_;
77  
78 10 my $now = current_datetime();
79 0 my $self = {
80 string => undef,
81 xml_doc => undef,
82 xml_root => undef,
83 _xml_payload => undef,
84 _payload => undef,
85 _timestamp => cxml_timestamp($now),
86 epoch => $now->strftime('%s'),
87 hostname => hostname,
88 randint => int(rand(99999999)),
89 pid => $$,
90 test => 0,
91 _lang => 'en-US',
92 _id => undef,
93 _inreplyto => undef,
94 status => {
95 code => 200,
96 text => 'OK',
97 description => '',
98 },
99 class => '',
100 _type => '',
101 _from => undef,
102 _to => undef,
103 _sender => undef,
104 };
105 0 bless $self, $class;
106  
107 0 ▶ if ($input) {
Branch: 1 branch
BranchTrueFalseTotal
if ($input) { } 0 0 0
108 0 my $doc;
109 0 ▶ $input = decode_base64($input) unless ($input =~ /^\s*</);
Branch: 1 branch
BranchTrueFalseTotal
unless $input =~ /^\s*</u 0 0 0
110 0 eval {
111 0 $self->{xml_doc} = ($doc = XML::LibXML->load_xml(string => $input));
112 };
113 0 ▶ return [ 400, $@ ] if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
114 0 eval {
115 0 my $dtd = XML::LibXML::Dtd->new(undef, "http://xml.cxml.org/schemas/cXML/" . $Business::cXML::CXML_VERSION . "/cXML.dtd");
116 0 $doc->validate($dtd);
117 };
118 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
119 0 eval {
120 0 $doc->validate();
121 };
122 0 ▶ return [ 406, $@ ] if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
123 };
124  
125 0 $self->{xml_root} = ($doc = $doc->documentElement);
126 0 $doc->ferry($self, {
127 version => '__UNIMPLEMENTED',
128 payloadID => '_id',
129 # timestamp is implicit
130 signatureVersion => '__UNIMPLEMENTED',
131 'xml:lang' => '_lang',
132 Header => {
133 From => [ '_from', 'Business::cXML::Credential' ],
134 To => [ '_to', 'Business::cXML::Credential' ],
135 Sender => [ '_sender', 'Business::cXML::Credential' ],
136 Path => '__UNIMPLEMENTED',
137 OriginalDocument => '__UNIMPLEMENTED',
138 },
139 Request => [ '__IGNORE', \&_new_payload ],
140 Response => [ '__IGNORE', \&_new_payload ],
141 Message => [ '__IGNORE', \&_new_payload ],
142 'ds:Signature' => '__UNIMPLEMENTED',
143 });
144 0 $self->_rebuild_payload();
145 } else {
146 # Create a brand new XML document from scratch.
147 0 my $doc = $self->{xml_doc} = XML::LibXML::Document->new('1.0', 'UTF-8');
148 0 $doc->createInternalSubset('cXML', undef, "http://xml.cxml.org/schemas/cXML/" . $Business::cXML::CXML_VERSION . "/cXML.dtd");
149 0 my $root = $self->{xml_root} = $doc->createElement('cXML');
150 0 $self->{_id} = $self->{epoch} . '.' . $self->{pid} . '.' . $self->{randint} . '@' . $self->{hostname}; # payloadID/inReplyTo
151 $root->attr(
152 payloadID => $self->{_id},
153 timestamp => $self->{_timestamp},
154 'xml:lang' => $self->{_lang},
155 0 );
156 # UNIMPLEMENTED cXML: version? signatureVersion?
157 0 $doc->setDocumentElement($root);
158  
159 # Something initially valid which will be replaced by the user
160 0 $self->{_xml_payload} = $doc->createElement('ProfileRequest');
161 0 $self->{class} = CXML_CLASS_REQUEST;
162 0 $self->{_type} = 'Profile';
163 };
164 0 ▶ $self->{_from} = Business::cXML::Credential->new('From') unless defined $self->{_from};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_from"} 0 0 0
165 0 ▶ $self->{_to} = Business::cXML::Credential->new('To') unless defined $self->{_to};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_to"} 0 0 0
166 0 ▶ $self->{_sender} = Business::cXML::Credential->new('Sender') unless defined $self->{_sender};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_sender"} 0 0 0
167  
168 0 return $self;
169 }
170  
171 0 ▶sub _new_payload {
Subroutine _new_payload: not called CC=11 SCAR=48.8
172 0 my ($self, $msg) = @_;
173 0 my $status;
174  
175 0 ▶ $self->is_test(1) if (exists $msg->{deploymentMode} && $msg->{deploymentMode} eq 'test');
Branch: 1 branch
BranchTrueFalseTotal
if exists $msg->{"deploymentMode"} and $msg->{"deploymentMode"} eq "test" 0 0 0
Condition0%0/3
exists $msg->{"deploymentMode"} and $msg->{"deploymentMode"} eq "test"
!ll&&!rl&&r
000
MC/DC0%0/2
exists $msg->{"deploymentMode"} and $msg->{"deploymentMode"} eq "test"
exists $msg->{"deploymentMode"} $msg->{"deploymentMode"} eq "test"
Truth table0%0/3
A and B
A= exists $msg->{"deploymentMode"}B= $msg->{"deploymentMode"} eq "test"
ABresult
0X0
100
111
176 0 ▶ $self->{_inreplyto} = $msg->{inReplyTo} if exists $msg->{inReplyTo};
Branch: 1 branch
BranchTrueFalseTotal
if exists $msg->{"inReplyTo"} 0 0 0
177 # UNIMPLEMENTED Message/Request/Response: Id?
178  
179 0 foreach ($msg->childNodes) {
180 0 ▶ if ($_->nodeName eq 'Status') {
Branch: 2 branches
BranchTrueFalseTotal
if ($_->nodeName eq 'Status') { } 0 0 0
elsif ($_->nodeType == 1) { } 0 0 0
181 0 $status = $_;
182 } elsif ($_->nodeType == XML_ELEMENT_NODE) {
183 0 $self->{_xml_payload} = $msg = $_;
184 };
185 };
186 0 my $className;
187 0 ($self->{_type}, $className) = $msg->nodeName =~ /^(.*)(Request|Response|Message)$/;
188 0 ▶ $self->{class} = CXML_CLASS_MESSAGE if $className eq 'Message';
Branch: 1 branch
BranchTrueFalseTotal
if $className eq "Message" 0 0 0
189 0 ▶ $self->{class} = CXML_CLASS_REQUEST if $className eq 'Request';
Branch: 1 branch
BranchTrueFalseTotal
if $className eq "Request" 0 0 0
190 0 ▶ $self->{class} = CXML_CLASS_RESPONSE if $className eq 'Response';
Branch: 1 branch
BranchTrueFalseTotal
if $className eq "Response" 0 0 0
191  
192 0 ▶ if ($status) {
Branch: 1 branch
BranchTrueFalseTotal
if ($status) { } 0 0 0
193 0 $self->status($status->{code}, $status->textContent);
194 } else {
195 0 $self->status(200);
196 };
197  
198 0 return undef;
199 }
200  
201 0 ▶sub _rebuild_payload {
Subroutine _rebuild_payload: not called CC=4 SCAR=30.0
202 0 my ($self) = @_;
203  
204 0 ▶ return if defined $self->{_payload};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"_payload"} 0 0 0
205  
206 0 my $class = 'Message';
207 0 ▶ $class = 'Request' if $self->is_request;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_request 0 0 0
208 0 ▶ $class = 'Response' if $self->is_response;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_response 0 0 0
209  
210 0 $class = 'Business::cXML::' . $class . '::' . $self->type;
211  
212 0 eval {
213 0 my $file = $class;
214 0 $file =~ s|::|/|g;
215 0 require "$file.pm";
216 0 $self->{_payload} = $class->new($self->{_xml_payload});
217 };
218 # Payload remains safely undef for unknown classes-types.
219 }
220  
221 =item C<B<toForm>( I<%arguments> )>
222  
223 In a scalar context, returns an HTML string representation of the current cXML
224 data structure, in cXML "URL-Form-Encoding" (a C<form> with a hidden
225 C<cxml-base64> value). Returns an empty string if we have an internal error.
226  
227 To help identify problems, in a list context it returns an error string (or
228 C<undef>) and the HTML string (probably empty, depending on the type of error).
229  
230 Possible I<C<%arguments>> keys:
231  
232 =over
233  
234 =item C<B<url>>
235  
236 Mandatory, should be from a C<PunchOutSetupRequest/BrowserFormPost>.
237  
238 =item C<B<target>>
239  
240 Optional, the HTML frame target to specify in the FORM
241  
242 =item C<B<submit_button>>
243  
244 Optional, override submit button HTML with your own
245  
246 =back
247  
248 =cut
249  
250 0 ▶sub toForm {
Subroutine toForm: not called CC=5 SCAR=34.0
Pod documented
251 0 my ($self, %args) = @_;
252 0 ▶ my $url = encode_entities($args{url} || '');
Condition0%0/2
$args{'url'} || ''
l!l
00
MC/DC0%0/1
$args{'url'} || ''
$args{'url'}
Truth table0%0/2
A
A= $args{'url'}
Aresult
11
00
253 0 my $submit = '<input type="submit">';
254 0 ▶ $submit = $args{submit_button} if exists $args{submit_button};
Branch: 1 branch
BranchTrueFalseTotal
if exists $args{"submit_button"} 0 0 0
255 0 my $target = '';
256 0 ▶ $target = ' target="' . encode_entities($args{target}) . '"' if defined $args{target};
Branch: 1 branch
BranchTrueFalseTotal
if defined $args{"target"} 0 0 0
257  
258 0 my ($err, $msg) = $self->toString;
259 0 ▶ return ($err, '') if defined $err;
Branch: 1 branch
BranchTrueFalseTotal
if defined $err 0 0 0
260  
261 0 $msg = encode_base64($msg, '');
262 0 return (undef, "<form method=\"post\" action=\"$url\"$target><input type=\"hidden\" name=\"cxml-base64\" value=\"$msg\">$submit</form>");
263 }
264  
265 =item C<B<toString>()>
266  
267 In a scalar context, returns an XML string representation of the current cXML
268 data structure.
269  
270 In the event that our XML document were not valid, a hard-coded C<500> status
271 C<Response> with explanation will be returned instead of the prepared
272 transmission.
273  
274 To help identify problems, in a list context it returns an error string (or
275 C<undef>) and the XML string.
276  
277 =cut
278  
279 0 ▶sub _valid_string {
Subroutine _valid_string: not called CC=2 SCAR=17.9
280 0 my ($self) = @_;
281 0 my $head = qq(<?xml version="1.0" encoding="UTF-8"?>\n)
282 . qq(<!DOCTYPE cXML SYSTEM "http://xml.cxml.org/schemas/cXML/)
283 . $Business::cXML::CXML_VERSION
284 . qq(/cXML.dtd">\n);
285 0 eval {
286 0 $self->{xml_doc}->validate();
287 };
288 0 ▶ if ($@) {
Branch: 1 branch
BranchTrueFalseTotal
if ($@) 0 0 0
289 0 return ($@, $head . qq(<cXML timestamp=") . $self->{_timestamp} . qq(" payloadID=") . $self->{_id} . qq(" xml:lang="en-US"><Response><Status code="500" text="Internal Server Error">) . encode_entities($@) . qq(</Status></Response></cXML>));
290 };
291 0 return (undef, $self->{xml_doc}->toString);
292 }
293  
294 0 ▶sub toString {
Subroutine toString: not called CC=18 SCAR=58.3
Pod documented
295 0 my ($self) = @_;
296  
297 0 ▶ return (undef, $self->{string}) if defined $self->{string};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"string"} 0 0 0
298  
299 0 $_->unbindNode() foreach ($self->{xml_root}->childNodes); # Start from guaranteed empty doc
300  
301  
302 0 ▶ unless ($self->is_response) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->is_response) 0 0 0
303 0 my $header = $self->{xml_root}->add('Header');
304 0 $header->add($self->{_from}->to_node($header));
305 0 $header->add($self->{_to}->to_node($header));
306 0 ▶ $self->{_sender}->secret(undef) if $self->is_message; # No SharedSecret in Message
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_message 0 0 0
307 0 $header->add($self->{_sender}->to_node($header));
308 # UNIMPLEMENTED: (Path OriginalDocument)?
309 };
310  
311 0 my $wrapper;
312 my $className;
313 0 ▶ $className = 'Message' if $self->is_message;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_message 0 0 0
314 0 ▶ $className = 'Request' if $self->is_request;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_request 0 0 0
315 0 ▶ $className = 'Response' if $self->is_response;
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_response 0 0 0
316 0 $wrapper = $self->{xml_root}->add($className);
317 0 ▶ $wrapper->attr(deploymentMode => ($self->{test} ? 'test' : 'production')) unless $self->is_response;
Branch: 2 branches
BranchTrueFalseTotal
unless $self->is_response 0 0 0
$self->{'test'} ? : 0 0 0
318 0 ▶ $wrapper->attr(inReplyTo => $self->{_inreplyto}) if $self->is_message && $self->{_inreplyto};
Branch: 1 branch
BranchTrueFalseTotal
if $self->is_message and $self->{"_inreplyto"} 0 0 0
Condition0%0/3
$self->is_message and $self->{"_inreplyto"}
!ll&&!rl&&r
000
MC/DC0%0/2
$self->is_message and $self->{"_inreplyto"}
$self->is_message $self->{"_inreplyto"}
Truth table0%0/3
A and B
A= $self->is_messageB= $self->{"_inreplyto"}
ABresult
0X0
100
111
319 # UNIMPLEMENTED Message/Request/Response: Id?
320  
321 0 ▶ if ($self->is_response || ($self->is_message && $self->{status}{code} != 200)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->is_response or $self->is_message and $self->{"status"}{"code"} != 200) 0 0 0
Condition0%0/6
$self->is_response or $self->is_message and $self->{"status"}{"code"} != 200
l!l&&r!l&&!r
000
$self->is_message and $self->{"status"}{"code"} != 200
!ll&&!rl&&r
000
MC/DC0%0/3
$self->is_response or $self->is_message and $self->{"status"}{"code"} != 200
$self->is_response $self->is_message $self->{"status"}{"code"} != 200
Truth table0%0/4
A or B and C
A= $self->is_responseB= $self->is_messageC= $self->{"status"}{"code"} != 200
ABCresult
1XX1
0111
00X0
0100
322 $wrapper->add('Status', $self->{status}{description},
323 code => $self->{status}{code},
324 'xml:lang' => 'en-US', # Our status descriptions are always in English
325 text => $self->{status}{text}
326 0 );
327 };
328  
329 # No payload on error or ping response
330 0 ▶ return $self->_valid_string if $self->{status}{code} >= 300 || $self->{status}{description} eq 'Pong!';
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"status"}{"code"} >= 300 or $self->{"status"}{"description"} eq "Pong!" 0 0 0
Condition0%0/3
$self->{"status"}{"code"} >= 300 or $self->{"status"}{"description"} eq "Pong!"
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->{"status"}{"code"} >= 300 or $self->{"status"}{"description"} eq "Pong!"
$self->{"status"}{"code"} >= 300 $self->{"status"}{"description"} eq "Pong!"
Truth table0%0/3
A or B
A= $self->{"status"}{"code"} >= 300B= $self->{"status"}{"description"} eq "Pong!"
ABresult
1X1
011
000
331  
332 0 ▶ if (ref $self->{_payload}) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $self->{"_payload"}) 0 0 0
333 # Optional native payload has precedence over XML payload.
334 0 $self->{_xml_payload} = $self->{_payload}->to_node($self->{xml_root});
335 };
336 0 $self->{_xml_payload}->setNodeName($self->{_type} . $className);
337 0 $wrapper->addChild($self->{_xml_payload});
338  
339 0 return $self->_valid_string;
340 }
341  
342 =item C<B<freeze>()>
343  
344 Store the results of L</toString()> internally and return it (in a scalar
345 context). This is what L</toString()> will always return until L</thaw()> is
346 eventually called. Has no effect if the transmission is already frozen.
347  
348 This helps comply with cXML's recommendation that multiple attempts to deliver
349 a transmission have the same C<payloadID> and C<timestamp> values.
350  
351 To help identify problems, in a list context it returns an error string (or
352 C<undef>) and the XML string. Note that multiple calls will only yield an error
353 (if any) on the first call, and C<undef> thereafter.
354  
355 =cut
356  
357 0 ▶sub freeze {
Subroutine freeze: not called CC=1 SCAR=6.9
Pod documented
358 0 my ($self) = @_;
359 0 my $err;
360 my $str;
361 0 ($err, $str) = $self->toString;
362 0 $self->{string} = $str;
363 0 return ($err, $self->{string});
364 }
365  
366 =item C<B<thaw>()>
367  
368 Destroy the internally stored results of L</toString()>. Modifications to
369 internal data will once again produce changes in what L</toString()> returns.
370  
371 =cut
372  
373 0 ▶sub thaw {
Subroutine thaw: not called CC=1 SCAR=6.9
Pod documented
374 0 my ($self) = @_;
375 0 $self->{string} = undef;
376 }
377  
378 =item C<B<reply_to>( REQUEST )>
379  
380 Initialize L</type>, L</inreplyto>, L</from>, L</to> and L</sender> in
381 reciprocity with request data.
382  
383 =cut
384  
385 0 ▶sub reply_to {
Subroutine reply_to: not called CC=1 SCAR=6.9
Pod documented
386 0 my ($self, $req) = @_;
387  
388 0 $self->{_type} = $req->{_type};
389  
390 0 $self->inreplyto($req->{_id});
391 0 $self->is_test($req->is_test);
392  
393 0 $self->sender->copy($req->to);
394 0 $self->sender->contact(undef);
395 0 $self->sender->secret($req->sender->secret);
396  
397 0 $self->from->copy($req->to);
398 0 $self->from->contact(undef);
399  
400 0 $self->to->copy($req->from);
401 0 $self->to->contact(undef);
402 }
403  
404 =item C<B<from>( [I<%properties>] )>
405  
406 =item C<B<to>( [I<%properties>] )>
407  
408 =item C<B<sender>( [I<%properties>] )>
409  
410 Returns the associated L<Business::cXML::Credential> object.
411  
412 With I<C<%properties>>, it first calls
413 L<Business::cXML::Credential::set()|Business::cXML::Credential/set>. In the
414 case of C<from()>, sets both C<from> and C<sender> objects, therefore if you
415 need to override this behavior, be sure to set C<sender> after C<from>.
416  
417 Note that you could also pass a single L<Business::cXML::Credential> object,
418 in which case it would replace the current one outright. In the case of
419 C<from()>, note that the object reference will be given to C<sender> intact
420 and a clone will be copied into C<from()>.
421  
422 =cut
423  
424 0 ▶sub from {
Subroutine from: not called CC=3 SCAR=24.8
Pod documented
425 0 my ($self, %props) = @_;
426 0 ▶ if (ref($_[1])) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $_[1]) { } 0 0 0
elsif (%props) { } 0 0 0
427 0 $self->{_from} = clone($self->{_sender} = $_[1]);
428 } elsif (%props) {
429 0 $self->{_sender}->set(%props);
430 0 $self->{_from}->set(%props);
431 };
432 0 return $self->{_from};
433 }
434  
435 0 ▶sub to {
Subroutine to: not called CC=3 SCAR=24.8
Pod documented
436 0 my ($self, %props) = @_;
437 0 ▶ if (ref($_[1])) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $_[1]) { } 0 0 0
elsif (%props) { } 0 0 0
438 0 $self->{_to} = $_[1];
439 } elsif (%props) {
440 0 $self->{_to}->set(%props);
441 };
442 0 return $self->{_to};
443 }
444  
445 0 ▶sub sender {
Subroutine sender: not called CC=3 SCAR=24.8
Pod documented
446 0 my ($self, %props) = @_;
447 0 ▶ if (ref($_[1])) {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $_[1]) { } 0 0 0
elsif (%props) { } 0 0 0
448 0 $self->{_sender} = $_[1];
449 } elsif (%props) {
450 0 $self->{_sender}->set(%props);
451 };
452 0 return $self->{_sender};
453 }
454  
455 =item C<B<is_test>( [I<$bool>] )>
456  
457 Get/set whether this transmission is in test mode (vs production).
458  
459 =cut
460  
461 0 ▶sub is_test {
Subroutine is_test: not called CC=3 SCAR=24.8
Pod documented
462 0 my ($self, $test) = @_;
463 0 ▶ $self->{test} = ($test ? 1 : 0) if @_ > 1;
Branch: 2 branches
BranchTrueFalseTotal
if @_ > 1 0 0 0
$test ? : 0 0 0
464 0 return $self->{test};
465 }
466  
467 =item C<B<timestamp>>
468  
469 Read-only, the transmission's creation date/time.
470  
471 =cut
472  
473 0 ▶sub timestamp { shift->{_timestamp} };
Subroutine timestamp: not called CC=1 SCAR=6.9
Pod documented
474  
475 =item C<B<id>>
476  
477 Read-only, the transmission's payload ID.
478  
479 =cut
480  
481 0 ▶sub id { shift->{_id} };
Subroutine id: not called CC=1 SCAR=6.9
Pod documented
482  
483 =item C<B<inreplyto>( [I<$id>] )>
484  
485 Get/set the payload ID of the transmission we're responding to.
486  
487 =cut
488  
489 0 ▶sub inreplyto {
Subroutine inreplyto: not called CC=2 SCAR=17.9
Pod documented
490 0 my ($self, $id) = @_;
491 0 ▶ $self->{_inreplyto} = $id if @_ > 1;
Branch: 1 branch
BranchTrueFalseTotal
if @_ > 1 0 0 0
492 0 return $self->{_inreplyto};
493 }
494  
495 =item C<B<is_message>( [I<$bool>] )>
496  
497 =item C<B<is_request>( [I<$bool>] )>
498  
499 =item C<B<is_response>( [I<$bool>] )>
500  
501 Get/set whether this transmission is a C<Message>, C<Request> or C<Response>.
502 The transmission's class is only modified when I<C<$bool>> is true.
503  
504 Setting any of these loses any data currently in L</payload>, so be sure to do
505 it early!
506  
507 =cut
508  
509 0 ▶sub is_message {
Subroutine is_message: not called CC=2 SCAR=17.9
Pod documented
510 0 my ($self, $bool) = @_;
511 0 ▶ if ($bool) {
Branch: 1 branch
BranchTrueFalseTotal
if ($bool) 0 0 0
512 0 $self->{class} = CXML_CLASS_MESSAGE;
513 0 $self->{_payload} = undef;
514 };
515 0 return $self->{class} == CXML_CLASS_MESSAGE;
516 }
517  
518 0 ▶sub is_request {
Subroutine is_request: not called CC=2 SCAR=17.9
Pod documented
519 0 my ($self, $bool) = @_;
520 0 ▶ if ($bool) {
Branch: 1 branch
BranchTrueFalseTotal
if ($bool) 0 0 0
521 0 $self->{class} = CXML_CLASS_REQUEST;
522 0 $self->{_payload} = undef;
523 };
524 0 return $self->{class} == CXML_CLASS_REQUEST;
525 }
526  
527 0 ▶sub is_response {
Subroutine is_response: not called CC=2 SCAR=17.9
Pod documented
528 0 my ($self, $bool) = @_;
529 0 ▶ if ($bool) {
Branch: 1 branch
BranchTrueFalseTotal
if ($bool) 0 0 0
530 0 $self->{class} = CXML_CLASS_RESPONSE;
531 0 $self->{_payload} = undef;
532 };
533 0 return $self->{class} == CXML_CLASS_RESPONSE;
534 }
535  
536 =item C<B<lang>( [I<$code>] )>
537  
538 Get/set the language for displayable strings included in this transmission.
539 Can be changed, but cannot be unset. Default: C<en-US>. For an incoming
540 transmission, this should be a hint to the user's preferred display language.
541  
542 =cut
543  
544 0 ▶sub lang {
Subroutine lang: not called CC=2 SCAR=17.9
Pod documented
545 0 my ($self, $lang) = @_;
546 0 ▶ if (defined $lang) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $lang) 0 0 0
547 0 $self->{_lang} = $lang;
548 0 $self->{xml_root}->attr('xml:lang' => $lang);
549 };
550 0 return $self->{_lang};
551 }
552  
553 =item C<B<type>( [I<$name>] )>
554  
555 Get/set the type of document. Can be changed, but cannot be unset. For
556 example: C<Profile> or C<PunchOutSetup>.
557  
558 B<Caution:> Setting a type loses any data currently in L</payload>, so be sure
559 to do it early!
560  
561 =cut
562  
563 0 ▶sub type {
Subroutine type: not called CC=2 SCAR=17.9
Pod documented
564 0 my ($self, $type) = @_;
565 0 ▶ if (defined $type) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $type) 0 0 0
566 0 $self->{_type} = $type;
567 0 $self->{_payload} = undef;
568 };
569 0 return $self->{_type};
570 }
571  
572 =item C<B<payload>>
573  
574 Read-only. If a native implementation for the current transmission type is
575 available (i.e. L<Business::cXML::Request::PunchOutSetup>), it is made
576 available ready-to-use via this property. For incoming transmission, it is
577 fully populated with parsed data.
578  
579 If accessed after previously using L</xml_payload>, this would cause the
580 native payload to be recreated from the XML payload as it currently stands,
581 preserving any (valid) changes done on the XML side into the native version.
582  
583 =cut
584  
585 0 ▶sub payload {
Subroutine payload: not called CC=1 SCAR=6.9
Pod documented
586 0 my ($self) = @_;
587 0 $self->_rebuild_payload();
588 0 return $self->{_payload};
589 }
590  
591 =item C<B<xml_payload>>
592  
593 Read-only. The L<XML::LibXML::Element> representing the "SomethingMessage",
594 "SomethingRequest" or "SomethingResponse" section of the transmission.
595  
596 Its node name is automatically determined in L</toString()>, but you are free
597 to add/change other attributes and child elements. Returns C<undef> for
598 incoming (parsed) transmissions.
599  
600 Accessing this property causes the destruction of L</payload> if it existed.
601 This is in place so that your own parsing of LibXML structures takes
602 precedence over ours to hopefully make future updates seamless in the event of
603 conflicts. Thus, while you can modify the native payload, then modify the XML
604 version, B<switching back again to native would lose all data>.
605  
606 =cut
607  
608 0 ▶sub xml_payload {
Subroutine xml_payload: not called CC=1 SCAR=6.9
Pod documented
609 0 my ($self) = @_;
610 0 $self->{_payload} = undef;
611 0 return $self->{_xml_payload};
612 }
613  
614 =item C<B<status>( [ I<$code>, [$description] ] )>
615  
616 Get/set transmission's cXML 3-digit status code. (None by default.)
617  
618 I<C<$description>> is an optional explanatory text that may be included in the
619 status of a response.
620  
621 cXML defines the following status codes, which are the only ones accepted.
622  
623 B<Success:>
624  
625 =over
626  
627 =item C<200> OK
628  
629 Request executed and delivered, cXML itself has no error
630  
631 =item C<201> Accepted
632  
633 Not yet processed, we'll send a StatusUpdate later
634  
635 =item C<204> No Content
636  
637 Request won't get a Response from server (i.e. punch-out cart didn't change)
638  
639 =item C<280> [Described like 201]
640  
641 =item C<281> [Described like 201]
642  
643 =back
644  
645 B<Permanent errors:>
646  
647 =over
648  
649 =item C<400> Bad Request
650  
651 Parsed OK but unacceptable
652  
653 =item C<401> Unauthorized
654  
655 Request/Sender credentials not recognized
656  
657 =item C<402> Payment Required
658  
659 Need complete Payment element
660  
661 =item C<403> Forbidden
662  
663 Insufficient privileges
664  
665 =item C<406> Not Acceptable
666  
667 Request unacceptable, likely parsing failure
668  
669 =item C<409> Conflict
670  
671 Current state incompatible with Request
672  
673 =item C<412> Precondition Failed
674  
675 Unlike 403, the precondition was described in a previous response
676  
677 =item C<417> Expectation Failed
678  
679 Request implied a resource condition that was not met, such as an unknown one
680  
681 =item C<450> Not Implemented
682  
683 Server doesn't implement that Request (so client ignored server's profile?)
684  
685 =item C<475> Signature Required
686  
687 Document missing required digital signature
688  
689 =item C<476> Signature Verification Failed
690  
691 Failed signature or unsupported signature algorithm
692  
693 =item C<477> Signature Unacceptable
694  
695 Valid signature but otherwise rejected
696  
697 =back
698  
699 B<Transient errors:>
700  
701 =over
702  
703 =item C<500> Internal Server Error
704  
705 Server was unable to complete the Request (temporary)
706  
707 =item C<550> Unable to reach cXML server
708  
709 Applies to intermediate hubs (temporary)
710  
711 =item C<551> Unable to forward request
712  
713 Because of supplier misconfiguration (temporary)
714  
715 =item C<560> Temporary server error
716  
717 Maintenance, etc. (temporary)
718  
719 =back
720  
721 =cut
722  
723 7 my %CXML_STATUS_CODES = (
724 200 => 'OK',
725 201 => 'Accepted',
726 204 => 'No Content',
727 280 => '',
728 281 => '',
729  
730 400 => 'Bad Request',
731 401 => 'Unauthorized',
732 402 => 'Payment Required',
733 403 => 'Forbidden',
734 406 => 'Not Acceptable',
735 409 => 'Conflict',
736 412 => 'Precondition Failed',
737 417 => 'Expectation Failed',
738 450 => 'Not Implemented',
739 475 => 'Signature Required',
740 476 => 'Signature Verification Failed',
741 477 => 'Signature Unacceptable',
742  
743 500 => 'Internal Server Error',
744 550 => 'Unable to reach cXML server',
745 551 => 'Unable to forward request',
746 560 => 'Temporary server error',
747 );
748  
749 0 ▶sub status {
Subroutine status: not called CC=4 SCAR=30.0
Pod documented
750 0 my ($self, $code, $desc) = @_;
751 0 ▶ if ($code) {
Branch: 1 branch
BranchTrueFalseTotal
if ($code) 0 0 0
752 0 ▶ if (exists $CXML_STATUS_CODES{$code}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $CXML_STATUS_CODES{$code}) { } 0 0 0
753 0 $self->{status}{code} = $code;
754 0 $self->{status}{text} = $CXML_STATUS_CODES{$code};
755 0 ▶ $self->{status}{description} = $desc || '';
Condition0%0/2
$desc || ''
l!l
00
MC/DC0%0/1
$desc || ''
$desc
Truth table0%0/2
A
A= $desc
Aresult
11
00
756 } else {
757 # We were given an unsupported code, this is BAD!
758 0 $self->{status}{code} = 500;
759 0 $self->{status}{text} = $CXML_STATUS_CODES{500};
760 0 $self->{status}{description} = "Unsupported actual status code '$code'.";
761 };
762 };
763 0 return $self->{status}{code};
764 }
765  
766 =back
767  
768 =head1 AUTHOR
769  
770 Stéphane Lavergne L<https://github.com/vphantom>
771  
772 =head1 ACKNOWLEDGEMENTS
773  
774 Graph X Design Inc. L<https://www.gxd.ca/> sponsored this project.
775  
776 =head1 COPYRIGHT & LICENSE
777  
778 Copyright (c) 2017-2018 Stéphane Lavergne L<https://github.com/vphantom>
779  
780 Permission is hereby granted, free of charge, to any person obtaining a copy
781 of this software and associated documentation files (the "Software"), to deal
782 in the Software without restriction, including without limitation the rights
783 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
784 copies of the Software, and to permit persons to whom the Software is
785 furnished to do so, subject to the following conditions:
786  
787 The above copyright notice and this permission notice shall be included in all
788 copies or substantial portions of the Software.
789  
790 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
791 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
792 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
793 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
794 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
795 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
796 SOFTWARE.
797  
798 =cut
799  
800 7 1;
« cXML/ItemIn.pm ↑ Summary cXML.pm »