Class ExchangeWS
- java.lang.Object
-
- ch.aeis.exchange.web.ws.exchange_1_0.ExchangeWS
-
public class ExchangeWS extends Object
The BVG Exchange Webservice.As webservices are by definition non transactional and we did not want to implement heavy weight WS Transaction protocols we require clients to acknowledge every action that isn't idempotent.
-
-
Constructor Summary
Constructors Constructor Description ExchangeWS()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
ackIncomingDocument(String userName, String password, String docIdent)
Acknowledges that aDocumentWS
requested in a previous call toretrieveIncomingDocument(String, String, String)
was received.void
ackReceipts(String userName, String password, Collection<String> docIdents)
Acknowledges the receipt of "delivery receipts" returned bygetPendingReceipts(String, String, String)
.boolean
ackSubmit(String userName, String password, String docIdent)
Acknowledges that a previous call tosubmitDocument(String, String, String)
has successfully returned.List<CompanyWS>
getAcceptingVes(String userName, String password, Collection<String> supportedExtendedValidations)
Returns a list of all VEs accepting incoming documents, i.e.DocumentWS
getDocument(String userName, String password, String docIdent)
Returns theDocumentWS
corresponding to the givendocIdent
.DocumentWS
getDocumentBySenderIdent(String userName, String password, String veUid, String senderIdent)
Returns aDocumentWS
based on thesenderIdent
defined and set by the sender.List<String>
getIncomingDocumentIdents(String userName, String password, String veUid)
Returns aList
of docIdents that are waiting to be retrieved by the caller.List<LogRecordWS>
getLogs(String userName, String password, String forUserName, String veUid, String docIdent, String action, String result, Date from, Date to, Integer maxResults, Integer offset, Boolean orderAsc)
Returns a list ofLogRecordWS
matching the given criteria.PdfWS
getPdf(String userName, String password, String docIdent, String language, Long ahvOrSozv, List<Integer> fzlPositions)
Returns aPdfWS
representation of the document corresponding to the givendocIdent
.List<LogRecordWS>
getPendingReceipts(String userName, String password, String veUid)
Returns all "delivery receipts" not yet retrieved and acknowledged.List<CompanyWS>
getVes(String userName, String password)
Returns a list of all registered VEs.String
ping()
Checks general availability of the webservice.DocumentWS
retrieveIncomingDocument(String userName, String password, String docIdent)
Retrieves an incomingDocumentWS
.PdfWS
retrieveIncomingPdf(String userName, String password, String docIdent)
BVG Exchange Internal method.boolean
revokeSubmit(String userName, String password, String docIdent)
Revokes previous call tosubmitDocument(String, String, String)
.String
submitDocument(String userName, String password, String xmlDoc)
Submits a xml document to the webservice.
-
-
-
Method Detail
-
ping
public String ping()
Checks general availability of the webservice.- Returns:
- Current date and version.
-
submitDocument
public String submitDocument(String userName, String password, String xmlDoc) throws ExchangeFault
Submits a xml document to the webservice.The submitted document is persisted. Processing continues after the submitter acknowledges the successful submit by calling
ackSubmit(String, String, String)
CALLING THIS METHOD BY ITSELF DOES (almost) NOTHING. You MUST acknowledge the submit.
If no acknowledge is received the submitted document will eventually be discarded.
- Parameters:
userName
- user namepassword
- passwordxmlDoc
-String
containing a complete XML Doc of a supported schema. The XML Doc MUST be explicitly UTF-8 encoded (<?xml version="1.0" encoding="UTF-8"?>
). BVG Exchange will deliver the submitted XML unchanged (unless migration between schema is required).- Returns:
docIdent
identifying this submit and document. ThisdocIdent
can be seen as the external primary key of the document and is used to reference this document in various other places.- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit for the 'ABSENDER' defined in
the submitted xml (
FaultCode.ILLEGAL_ACCESS
) - the xmlDoc is
null
or empty (FaultCode.XML_INVALID
) - the xmlDoc is invalid (
FaultCode.XML_INVALID
) - the xmlDoc is not explicitly UTF-8 encoded (
FaultCode.XML_INVALID
) - the xmlDoc is valid but of an unsupported type (at time of writing
FZL-1.2, FZL-1.3, FZL1-1.3.1, FZL-1.4
) (FaultCode.XML_INVALID
) - the xmlDoc violates default validation (described in the xsd-documentation)
(
FaultCode.XML_INVALID
) - the xmlDoc does not contain 'ABSENDER-Uid' and 'EMPFAENGER/ID' (unless postal delivery is activated)
in machine readable Swiss UID format (
FaultCode.XML_INVALID
) - the 'EMPFAENGER' is not configured to receive documents (unless postal delivery
is activated) (
FaultCode.RECIPIENT_INVALID
)
- the user is not authenticated
- See Also:
- Unternehmens-Identifikationsnummer (UID)
-
ackSubmit
public boolean ackSubmit(String userName, String password, String docIdent) throws ExchangeFault
Acknowledges that a previous call tosubmitDocument(String, String, String)
has successfully returned. Processing of a submitted document begins after this method is called. Calls to this method may be repeated.if for some reason the sender does not receive an answer from the webservice the sender has no way of knowing if the webservice has received and processed a submission or not. The sender would be forced to resend a "failed" submission potentially submitting data twice. The chosen sequence of submit/ack ensures that a document is submitted only once.
- Parameters:
userName
- user namepassword
- passworddocIdent
- theString
returned by a previous call tosubmitDocument(String, String, String)
- Returns:
true
if this call changed the status of the documentfalse
if the document submission was already acknowledged
- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit for the 'ABSENDER' defined in
the referenced document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent (
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated
-
revokeSubmit
public boolean revokeSubmit(String userName, String password, String docIdent) throws ExchangeFault
Revokes previous call tosubmitDocument(String, String, String)
. The revoke is possible as long as the receiver doesn't retrieve the document. The submitted document will not be processed after a revoke has occured.- Parameters:
userName
- user namepassword
- passworddocIdent
- theString
returned by a previous call tosubmitDocument(String, String, String)
- Returns:
true
if this call changed the status of the document
- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit for the 'ABSENDER' defined in
the referenced document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent (
FaultCode.ILLEGAL_ARGUMENT
) - the document has already been retrieved by the receiver (
FaultCode.ILLEGAL_STATE
)
- the user is not authenticated
-
getIncomingDocumentIdents
public List<String> getIncomingDocumentIdents(String userName, String password, String veUid) throws ExchangeFault
Returns aList
of docIdents that are waiting to be retrieved by the caller. If no documents are pending, an emptyList
is returned.If the parameter veUid is set, the scope is limited that specific recipient. Otherwise all docIdents the calling user may retrieve are returned.
docIdents will continue to be returned by this method until they are retrieved by calling
retrieveIncomingDocument(String, String, String)
and the retrieval is acknowledged by callingackIncomingDocument(String, String, String)
- Parameters:
userName
- user namepassword
- passwordveUid
- the UID of a specific sender VE in machine readable Swiss UID format. May benull
. If set only pending docIdents for that VE will be returned. Ifnull
all pending docIdents will be returned.- Returns:
- a list of docIdents waiting to be retrieved.
- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to receive documents for any VE or in case of an explicitly set
veUid the user is not authorized to receive documents for that VE
(
FaultCode.ILLEGAL_ACCESS
) - an explicitly set veUid is unknown or not correctly formatted
(
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated
- See Also:
- Unternehmens-Identifikationsnummer (UID)
-
retrieveIncomingDocument
public DocumentWS retrieveIncomingDocument(String userName, String password, String docIdent) throws ExchangeFault
Retrieves an incomingDocumentWS
. This call is the "official" delivery of a document and logged as such. It differs fromgetDocument(String, String, String)
in that, it changes the state of the document and may only be called when a document is in the stateStatusWS.PENDING_DELIVERY
orStatusWS.PENDING_ACK
.CALLING THIS METHOD BY ITSELF DOES (almost) NOTHING. You MUST acknowledge the retrieval.
A document will continue to be returned by
getIncomingDocumentIdents(String, String, String)
until the retrieval has been acknowledged by callingackIncomingDocument(String, String, String)
.This method will return a
DocumentWS
with only oneDocumentXmlWS
instance that is accepted by the recipient. If the original schema of a document is not accepted by the recipient, it will be migrated to a best-match accepted schema. (Existing migrated version, before new; up before down; 'nearest' schema version.)Please use
getDocument(String, String, String)
in order to retrieve allDocumentXmlWS
connected to a document.- Parameters:
userName
- user namepassword
- passworddocIdent
- one of theStrings
returned bygetIncomingDocumentIdents(String, String, String)
. This is the ident of the document to be retrieved.- Returns:
- A
DocumentWS
with only oneDocumentXmlWS
instance. - Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to receive documents for the VE defined as
'EMPFAENGER' in the requested document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent or
only the metadata (no xml-content) for the given docIdent exists (
FaultCode.ILLEGAL_ARGUMENT
) - the requested document is not in the state
StatusWS.PENDING_DELIVERY
orStatusWS.PENDING_ACK
(FaultCode.ILLEGAL_STATE
) - the recipient of the requested document is not registered to receive exchange documents
(
FaultCode.GENERIC
)
- the user is not authenticated
-
retrieveIncomingPdf
public PdfWS retrieveIncomingPdf(String userName, String password, String docIdent) throws ExchangeFault
BVG Exchange Internal method.Retrieves an incoming document as Pdf. This call is equivalent to
retrieveIncomingDocument(String, String, String)
.This call is only intended for special print and snail mail service providers. A
DocumentWS
that has been retrieved by calling this method can no longer be retrieved as XML by callingretrieveIncomingDocument(String, String, String)
. The rational is that there can only be one "official" delivery that triggers the receipt for the sender. Either the XML file or the PDF file, not both.The corresponding XML file is always available by calling
getDocument(String, String, String)
orgetDocumentBySenderIdent(String, String, String, String)
.- Parameters:
userName
- user namepassword
- passworddocIdent
- one of theStrings
returned bygetIncomingDocumentIdents(String, String, String)
. This is the ident of the document to be retrieved.- Returns:
- The requested
PdfWS
- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to receive documents for the VE defined as
'EMPFAENGER' in the requested document (
FaultCode.ILLEGAL_ACCESS
) - the user is not an authorized print service(
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent or
only the metadata (no pdf-content) for the given docIdent exists (
FaultCode.ILLEGAL_ARGUMENT
) - the requested document is not in the state
StatusWS.PENDING_DELIVERY
orStatusWS.PENDING_ACK
(FaultCode.ILLEGAL_STATE
)
- the user is not authenticated
-
ackIncomingDocument
public boolean ackIncomingDocument(String userName, String password, String docIdent) throws ExchangeFault
Acknowledges that aDocumentWS
requested in a previous call toretrieveIncomingDocument(String, String, String)
was received. After this call a document is regarded as "officially" delivered.A document will continue to be returned by
getIncomingDocumentIdents(String, String, String)
until retrieval has been acknowledged by calling this method.- Parameters:
userName
- user namepassword
- passworddocIdent
- the docIdent of the document previously retrieved- Returns:
true
if this call changed the status of the documentfalse
if the document receipt was already acknowledged
- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to receive documents for the VE defined as
'EMPFAENGER' in the requested document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent (
FaultCode.ILLEGAL_ARGUMENT
) - the requested document is not in the state
StatusWS.PENDING_ACK
(FaultCode.ILLEGAL_STATE
)
- the user is not authenticated
-
getPendingReceipts
public List<LogRecordWS> getPendingReceipts(String userName, String password, String veUid) throws ExchangeFault
Returns all "delivery receipts" not yet retrieved and acknowledged."Delivery receipts" are common log entries with
LogRecordWS.getAction()
= 'ACK_INCOMING
'. These log entries are confirmation of delivery to the recipient."Delivery receipts" will continue to be returned by this method until the receipt of these receipts is acknowledged by calling
ackReceipts(String, String, Collection)
.- Parameters:
userName
- user namepassword
- passwordveUid
- the UID of a specific sender in machine readable Swiss UID format. May benull
. If set only pending receipts for the VE will be returned. Ifnull
all pending receipts will be returned.- Returns:
List
of "delivery receipts".- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit documents at all or in case of the given veUid is explicitly
set and the user is not authorized to submit documents for this veUid
(
FaultCode.ILLEGAL_ACCESS
) - an explicitly set veUid is unknown or not correctly formatted
(
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated
- See Also:
- Unternehmens-Identifikationsnummer(UID)
-
ackReceipts
public void ackReceipts(String userName, String password, Collection<String> docIdents) throws ExchangeFault
Acknowledges the receipt of "delivery receipts" returned bygetPendingReceipts(String, String, String)
."Delivery receipts" will continue to be returned by
getPendingReceipts(String, String, String)
until the receipt of these receipts is acknowledged by calling this method.- Parameters:
userName
- user namepassword
- passworddocIdents
- a collection of docIdents for which the receipt of "delivery receipts" is to be acknowledged- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit documents for the VE defined as
'ABSENDER' in a document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with a given docIdent (
FaultCode.ILLEGAL_ARGUMENT
) - when a document referenced by the given docIdent has another state then
DocStatus.PENDING_RECEIPT
(FaultCode.ILLEGAL_STATE
)
- the user is not authenticated
-
getDocument
public DocumentWS getDocument(String userName, String password, String docIdent) throws ExchangeFault
Returns theDocumentWS
corresponding to the givendocIdent
.Only users that have submit, receive or get privileges for either the 'EMPFAENGER' or 'ABSENDER' are allowed to access documents.
Note: The returned
DocumentWS
may contain more than onexml
with different formats. This may occur whenever more than one schema is simultaneously supported and sender and recipient formats do not match. In this case BVG Exchange will migratexml
between formats, resulting in more than onexml
per document.- Parameters:
userName
- user namepassword
- passworddocIdent
- of the requested document- Returns:
DocumentWS
corresponding to the given docIdent- Throws:
ExchangeFault
- when- the user is not authenticated
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit/receive/get documents for the VE defined
as 'ABSENDER' or 'EMPFAENGER' in the document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent (
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated
-
getDocumentBySenderIdent
public DocumentWS getDocumentBySenderIdent(String userName, String password, String veUid, String senderIdent) throws ExchangeFault
Returns aDocumentWS
based on thesenderIdent
defined and set by the sender.All supported schema define an element
<IDENT>
with following definition:
IDENT is an arbitrary unique ID defined by the sender to identify this file. IDENT must be unique for a sender regardless of the date.The sender is responsible for setting unique
enderIdents
. BVG Exchange will not validate for uniquesenderIdents
. Non-uniquesenderIdents
will cause this method to throw an exception if thatsenderIdent
is requested.- Parameters:
userName
- user namepassword
- passwordveUid
- the UID of the sender in machine readable Swiss UID formatsenderIdent
- the senderIdent set and defined by the sender of the requested document- Returns:
DocumentWS
corresponding to the given senderIdent- Throws:
ExchangeFault
- when- the user is not authenticated (
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit/receive/get documents for the given VE
(
FaultCode.ILLEGAL_ACCESS
) - the given veUid is unknown or not correctly formatted (
FaultCode.ILLEGAL_ARGUMENT
) - no document with the given
senderIdent
was found (FaultCode.ILLEGAL_ARGUMENT
) - more than one document with the given
senderIdent
was found (FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated (
- See Also:
- Unternehmens-Identifikationsnummer (UID)
-
getPdf
public PdfWS getPdf(String userName, String password, String docIdent, String language, Long ahvOrSozv, List<Integer> fzlPositions) throws ExchangeFault
Returns aPdfWS
representation of the document corresponding to the givendocIdent
.Note:This method may return
null
. For the moment all submits will generate a PDF. This might not be necessary depending on ABSENDER/EMPFAENGER configurations and BVG Exchange reserves the right to limit PDF generation to those cases where PDFs are required.- Parameters:
userName
- user namepassword
- passworddocIdent
- of the requested documentlanguage
- optionally if language of pdf should not be the default languageahvOrSozv
- optionally define this filter if only the fzl with this ahv or sozv nr should be renderedfzlPositions
- optionally define this filter if only specific fzl should be rendered. 0 is the first fzl in the xml.- Returns:
- PDF representation of the requested document. May be null.
- Throws:
ExchangeFault
- when- the user is not authenticated (
FaultCode.WRONG_CREDENTIALS
) - the user is not authorized to submit/receive/get documents for the VE defined
as 'ABSENDER' or 'EMPFAENGER' in the document (
FaultCode.ILLEGAL_ACCESS
) - no document exists with the given docIdent or
only the metadata (no pdf-content) for the given docIdent exists (
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated (
-
getLogs
public List<LogRecordWS> getLogs(String userName, String password, String forUserName, String veUid, String docIdent, String action, String result, Date from, Date to, Integer maxResults, Integer offset, Boolean orderAsc) throws ExchangeFault
Returns a list ofLogRecordWS
matching the given criteria.A
user
may only access log records that directly affect the VE's for which theuser
has privileges.Note: Unless otherwise specified, invalid parameter values will not cause an exception to be thrown (e.g. veUid="CHE000000000" will not cause an exception). The only effect will be an empty result.
- Parameters:
userName
- user namepassword
- passwordforUserName
- if set onlyLogRecords
of actions byforUserName
are returned. At the time of writingusers
may only query their own LogRecords.veUid
- if set only log records of actions for the given VE are returned. The UID must be in machine readable Swiss UID format.docIdent
- if set only log records concerning the givendocIdent
are returned. Setting only this parameter returns the complete history of a specific document.action
- if set only log records with a matching action (SUBMIT, ACK_SUBMIT, GET_INCOMING_DOC_IDENTS, RETRIEVE_DOC, ACK_INCOMING, GET_RECEIPTS, ACK_RECEIPT, GET
) are returned. Unknown values will be ignored.result
- if set only log records with a matching result (SUCCESS, FAIL, SECURITY
) are returned. Unknown values will be ignored.from
- if set only log records equal or afterfrom
are returned.to
- if set only log records equal or beforeto
are returned.maxResults
- maximum number of results to be returned. The server limits this value to 1000. This method will returnmaxResults + 1
if more thanmaxResults
match the query.offset
- zero based offset for the results. This allows retrieval of missing log records if a previous query returned more thanmaxResults
orderAsc
- log records are queried ordered by timestamp. This parameter defines if ascending or descending.- true - ascending (default)
- false - descending
- Returns:
- list of
LogRecordWS
matching the given criteria - Throws:
ExchangeFault
- when- the user is not authenticated (
FaultCode.WRONG_CREDENTIALS
) - maxResults exceeds the allowed limit of 1000 (
FaultCode.ILLEGAL_ARGUMENT
)
- the user is not authenticated (
- See Also:
- Unternehmens-Identifikationsnummer (UID)
-
getVes
public List<CompanyWS> getVes(String userName, String password) throws ExchangeFault
Returns a list of all registered VEs.- Parameters:
userName
- user namepassword
- password- Returns:
- a list of all registered VEs.
- Throws:
ExchangeFault
- when the user is not authenticated (FaultCode.WRONG_CREDENTIALS
)- See Also:
getAcceptingVes(String, String, Collection)
-
getAcceptingVes
public List<CompanyWS> getAcceptingVes(String userName, String password, Collection<String> supportedExtendedValidations) throws ExchangeFault
Returns a list of all VEs accepting incoming documents, i.e. you can send documents to any VE returned here.The parameter 'supportedExtendedValidations' is no longer supported. (The concept of fine grained quality contracts between sender and recipient has never caught on and is - in retrospect - to complicated. We're leaving the method signature in place in order not to break existing client impls.)
- Parameters:
userName
- user namepassword
- passwordsupportedExtendedValidations
- No longer supported. Ignored.- Returns:
- a list of all accepting VEs
- Throws:
ExchangeFault
- when the user is not authenticated (FaultCode.WRONG_CREDENTIALS
)
-
-