Package ch.aeis.exchange.web.ws.exchange_1_0

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 Details

    • ExchangeWS

      public ExchangeWS()

  • Method Details

    • 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 name
      password - password
      xmlDoc - 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. This docIdent 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
      See Also:

    • ackSubmit

      public boolean ackSubmit(String userName, String password, String docIdent) throws ExchangeFault
      Acknowledges that a previous call to submitDocument(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 name
      password - password
      docIdent - the String returned by a previous call to submitDocument(String, String, String)
      Returns:
      • true if this call changed the status of the document
      • false if the document submission was already acknowledged
      Throws:
      ExchangeFault - when

    • revokeSubmit

      public boolean revokeSubmit(String userName, String password, String docIdent) throws ExchangeFault
      Revokes previous call to submitDocument(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 name
      password - password
      docIdent - the String returned by a previous call to submitDocument(String, String, String)
      Returns:
      • true if this call changed the status of the document
      Throws:
      ExchangeFault - when

    • getIncomingDocumentIdents

      public List<String> getIncomingDocumentIdents(String userName, String password, String veUid) throws ExchangeFault
      Returns a List of docIdents that are waiting to be retrieved by the caller. If no documents are pending, an empty List 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 calling ackIncomingDocument(String, String, String)

      Parameters:
      userName - user name
      password - password
      veUid - the UID of a specific sender VE in machine readable Swiss UID format. May be null. If set only pending docIdents for that VE will be returned. If null all pending docIdents will be returned.
      Returns:
      a list of docIdents waiting to be retrieved.
      Throws:
      ExchangeFault - when
      See Also:

    • retrieveIncomingDocument

      public DocumentWS retrieveIncomingDocument(String userName, String password, String docIdent) throws ExchangeFault
      Retrieves an incoming DocumentWS. This call is the "official" delivery of a document and logged as such. It differs from getDocument(String, String, String) in that, it changes the state of the document and may only be called when a document is in the state StatusWS.PENDING_DELIVERY or StatusWS.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 calling ackIncomingDocument(String, String, String).

      This method will return a DocumentWS with only one DocumentXmlWS 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 all DocumentXmlWS connected to a document.

      Parameters:
      userName - user name
      password - password
      docIdent - one of the Strings returned by getIncomingDocumentIdents(String, String, String). This is the ident of the document to be retrieved.
      Returns:
      A DocumentWS with only one DocumentXmlWS instance.
      Throws:
      ExchangeFault - when

    • 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 calling retrieveIncomingDocument(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) or getDocumentBySenderIdent(String, String, String, String).

      Parameters:
      userName - user name
      password - password
      docIdent - one of the Strings returned by getIncomingDocumentIdents(String, String, String). This is the ident of the document to be retrieved.
      Returns:
      The requested PdfWS
      Throws:
      ExchangeFault - when

    • ackIncomingDocument

      public boolean ackIncomingDocument(String userName, String password, String docIdent) throws ExchangeFault
      Acknowledges that a DocumentWS requested in a previous call to retrieveIncomingDocument(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 name
      password - password
      docIdent - the docIdent of the document previously retrieved
      Returns:
      • true if this call changed the status of the document
      • false if the document receipt was already acknowledged
      Throws:
      ExchangeFault - when

    • 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 name
      password - password
      veUid - the UID of a specific sender in machine readable Swiss UID format. May be null. If set only pending receipts for the VE will be returned. If null all pending receipts will be returned.
      Returns:
      List of "delivery receipts".
      Throws:
      ExchangeFault - when
      See Also:

    • ackReceipts

      public void ackReceipts(String userName, String password, Collection<String> docIdents) throws ExchangeFault
      Acknowledges the receipt of "delivery receipts" returned by getPendingReceipts(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 name
      password - password
      docIdents - a collection of docIdents for which the receipt of "delivery receipts" is to be acknowledged
      Throws:
      ExchangeFault - when

    • getDocument

      public DocumentWS getDocument(String userName, String password, String docIdent) throws ExchangeFault
      Returns the DocumentWS corresponding to the given docIdent.

      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 one xml 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 migrate xml between formats, resulting in more than one xml per document.

      Parameters:
      userName - user name
      password - password
      docIdent - of the requested document
      Returns:
      DocumentWS corresponding to the given docIdent
      Throws:
      ExchangeFault - when

    • getDocumentBySenderIdent

      public DocumentWS getDocumentBySenderIdent(String userName, String password, String veUid, String senderIdent) throws ExchangeFault
      Returns a DocumentWS based on the senderIdent defined and set by the sender.

      All supported schema define an element &lt;IDENT&gt; 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 unique senderIdents. Non-unique senderIdents will cause this method to throw an exception if that senderIdent is requested.

      Parameters:
      userName - user name
      password - password
      veUid - the UID of the sender in machine readable Swiss UID format
      senderIdent - the senderIdent set and defined by the sender of the requested document
      Returns:
      DocumentWS corresponding to the given senderIdent
      Throws:
      ExchangeFault - when
      See Also:

    • getPdf

      public PdfWS getPdf(String userName, String password, String docIdent, String language, Long ahvOrSozv, List<Integer> fzlPositions) throws ExchangeFault
      Returns a PdfWS representation of the document corresponding to the given docIdent.

      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 name
      password - password
      docIdent - of the requested document
      language - optionally if language of pdf should not be the default language
      ahvOrSozv - optionally define this filter if only the fzl with this ahv or sozv nr should be rendered
      fzlPositions - 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

    • 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 of LogRecordWS matching the given criteria.

      A user may only access log records that directly affect the VE's for which the user 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 name
      password - password
      forUserName - if set only LogRecords of actions by forUserName are returned. At the time of writing users 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 given docIdent 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 after from are returned.
      to - if set only log records equal or before to are returned.
      maxResults - maximum number of results to be returned. The server limits this value to 1000. This method will return maxResults + 1 if more than maxResults match the query.
      offset - zero based offset for the results. This allows retrieval of missing log records if a previous query returned more than maxResults
      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
      See Also:

    • getVes

      public List<CompanyWS> getVes(String userName, String password) throws ExchangeFault
      Returns a list of all registered VEs.
      Parameters:
      userName - user name
      password - password
      Returns:
      a list of all registered VEs.
      Throws:
      ExchangeFault - when the user is not authenticated (FaultCode.WRONG_CREDENTIALS)
      See Also:

    • 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 name
      password - password
      supportedExtendedValidations - No longer supported. Ignored.
      Returns:
      a list of all accepting VEs
      Throws:
      ExchangeFault - when the user is not authenticated (FaultCode.WRONG_CREDENTIALS)