NAME
Business::cXML::Transmission - cXML transmission
SYNOPSIS
use Business::cXML::Transmission;
$msg = parse Business::cXML::Transmission $incoming_cxml_string;DESCRIPTION
Parser and compiler for cXML transmissions.
See: http://xml.cxml.org/current/cXMLUsersGuide.pdf
The creation of these transmissions should normally be left to Business::cXML, which does some handy initialization for you. Of main concern for manual processing is our "payload()".
METHODS
new( [$input] )-
Without
$input, returns an empty Business::cXML::Transmission ready to be populated.With
$input, returns a Business::cXML::Transmission if parsing was possible, or an arrayref with two elements if there was an error. The first element is a status code, and the second contains a string with more details, if available. Input is expected to be a full XML document string, optionally encoded in Base64 (i.e. the contents of acxml-base64form variable).Possible codes:
toForm( %arguments )-
In a scalar context, returns an HTML string representation of the current cXML data structure, in cXML "URL-Form-Encoding" (a
formwith a hiddencxml-base64value). Returns an empty string if we have an internal error.To help identify problems, in a list context it returns an error string (or
undef) and the HTML string (probably empty, depending on the type of error).Possible
%argumentskeys:url-
Mandatory, should be from a
PunchOutSetupRequest/BrowserFormPost. target-
Optional, the HTML frame target to specify in the FORM
-
Optional, override submit button HTML with your own
toString()-
In a scalar context, returns an XML string representation of the current cXML data structure.
In the event that our XML document were not valid, a hard-coded
500statusResponsewith explanation will be returned instead of the prepared transmission.To help identify problems, in a list context it returns an error string (or
undef) and the XML string. freeze()-
Store the results of "toString()" internally and return it (in a scalar context). This is what "toString()" will always return until "thaw()" is eventually called. Has no effect if the transmission is already frozen.
This helps comply with cXML's recommendation that multiple attempts to deliver a transmission have the same
payloadIDandtimestampvalues.To help identify problems, in a list context it returns an error string (or
undef) and the XML string. Note that multiple calls will only yield an error (if any) on the first call, andundefthereafter. thaw()-
Destroy the internally stored results of "toString()". Modifications to internal data will once again produce changes in what "toString()" returns.
reply_to( REQUEST )-
Initialize "type", "inreplyto", "from", "to" and "sender" in reciprocity with request data.
from( [%properties] )to( [%properties] )sender( [%properties] )-
Returns the associated Business::cXML::Credential object.
With
%properties, it first calls Business::cXML::Credential::set(). In the case offrom(), sets bothfromandsenderobjects, therefore if you need to override this behavior, be sure to setsenderafterfrom.Note that you could also pass a single Business::cXML::Credential object, in which case it would replace the current one outright. In the case of
from(), note that the object reference will be given tosenderintact and a clone will be copied intofrom(). is_test( [$bool] )-
Get/set whether this transmission is in test mode (vs production).
timestamp-
Read-only, the transmission's creation date/time.
id-
Read-only, the transmission's payload ID.
inreplyto( [$id] )-
Get/set the payload ID of the transmission we're responding to.
is_message( [$bool] )is_request( [$bool] )is_response( [$bool] )-
Get/set whether this transmission is a
Message,RequestorResponse. The transmission's class is only modified when$boolis true.Setting any of these loses any data currently in "payload", so be sure to do it early!
lang( [$code] )-
Get/set the language for displayable strings included in this transmission. Can be changed, but cannot be unset. Default:
en-US. For an incoming transmission, this should be a hint to the user's preferred display language. type( [$name] )-
Get/set the type of document. Can be changed, but cannot be unset. For example:
ProfileorPunchOutSetup.Caution: Setting a type loses any data currently in "payload", so be sure to do it early!
payload-
Read-only. If a native implementation for the current transmission type is available (i.e. Business::cXML::Request::PunchOutSetup), it is made available ready-to-use via this property. For incoming transmission, it is fully populated with parsed data.
If accessed after previously using "xml_payload", this would cause the native payload to be recreated from the XML payload as it currently stands, preserving any (valid) changes done on the XML side into the native version.
xml_payload-
Read-only. The XML::LibXML::Element representing the "SomethingMessage", "SomethingRequest" or "SomethingResponse" section of the transmission.
Its node name is automatically determined in "toString()", but you are free to add/change other attributes and child elements. Returns
undeffor incoming (parsed) transmissions.Accessing this property causes the destruction of "payload" if it existed. This is in place so that your own parsing of LibXML structures takes precedence over ours to hopefully make future updates seamless in the event of conflicts. Thus, while you can modify the native payload, then modify the XML version, switching back again to native would lose all data.
status( [ $code, [$description] ] )-
Get/set transmission's cXML 3-digit status code. (None by default.)
$descriptionis an optional explanatory text that may be included in the status of a response.cXML defines the following status codes, which are the only ones accepted.
Success:
200OK-
Request executed and delivered, cXML itself has no error
201Accepted-
Not yet processed, we'll send a StatusUpdate later
204No Content-
Request won't get a Response from server (i.e. punch-out cart didn't change)
280[Described like 201]281[Described like 201]
Permanent errors:
400Bad Request-
Parsed OK but unacceptable
-
Request/Sender credentials not recognized
402Payment Required-
Need complete Payment element
403Forbidden-
Insufficient privileges
406Not Acceptable-
Request unacceptable, likely parsing failure
409Conflict-
Current state incompatible with Request
412Precondition Failed-
Unlike 403, the precondition was described in a previous response
417Expectation Failed-
Request implied a resource condition that was not met, such as an unknown one
450Not Implemented-
Server doesn't implement that Request (so client ignored server's profile?)
475Signature Required-
Document missing required digital signature
476Signature Verification Failed-
Failed signature or unsupported signature algorithm
477Signature Unacceptable-
Valid signature but otherwise rejected
Transient errors:
AUTHOR
Stéphane Lavergne https://github.com/vphantom
ACKNOWLEDGEMENTS
Graph X Design Inc. https://www.gxd.ca/ sponsored this project.
COPYRIGHT & LICENSE
Copyright (c) 2017-2018 Stéphane Lavergne https://github.com/vphantom
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.