package examples.xml.biztalk;

/**
 * Interface describing a Biztalk document that has been received by a 
 * Biztalk Server. Objects implementing this interface are 
 * passed to EJBs registered with a Biztalk server based
 * on the document type returned by the  getType() method.
 *
 * @author Copyright (c) 2000 by BEA Systems, Inc. All Rights Reserved.
 */

public interface IncomingMessage extends java.io.Serializable {

  /**
   * Returns XML for the original document
   *
   * @return XML document 
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getXML() throws BizException;

  /**
   * Returns Document type for the payload. The document type is name
   * of the first element in the body of the document.
   *
   * @return Document type.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getType() throws BizException;

  /**
   * Returns name space associated with the payload. The name space
   * identifies the schema used by the payload (body) of the
   * document.
   *
   * @return Envelope name space.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getNameSpace() throws BizException;

  /**
   * Returns name space associated with the Biztalk envelope. The name space
   * identifies the schema used by the Biztalk envelope.
   *
   * @return Envelope name space.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getBizNameSpace() throws BizException;

  /**
   * Returns address of sender. The address is a Universal Resource Identifier (URI) describing the logical address of the sending or receiving system.  It is resolved to a transport-specific system address by the BizTalk server.  This transport-specific address is transparent to the applications.  
   *
   * @return URI of sender.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getFromAddress() throws BizException;

  /**
   * Returns reference ID of sender.   A reference ID is a unique identifier or cookie used to reference which interchange this document is associated with.  The reference ID for the document interchange would typically be unique for an instance of a particular business process.
   *
   * @return Sender reference ID.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getFromReferenceID() throws BizException;


  /**
   * Returns state info set by the sender. Process may be used to again refine the state of the interchange, by identifying the user account, process, or security context where the document originated, or is intended to be sent.  This is a further refinement of the <I>handle</I>.
   *
   * @return Process value.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getFromProcess() throws BizException;

  /**
   * Returns state info set by the sender. Handle provides additional handling or processing information that may be required by the application.  An example would be the handle for a functional module or step within a business process.  The handle is used as a further refinement of the reference ID.
   *
   * @return Handle value.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getFromHandle() throws BizException;

  // to block
  /**
   * Returns address of receiver. The address is a Universal Resource Identifier (URI) describing the logical address of the sending or receiving system.  It is resolved to a transport-specific system address by the BizTalk server.  This transport-specific address is transparent to the applications.  
   *
   * @return URI of message recipient.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getToAddress() throws BizException;

  /**
   * Returns reference ID of recipient.   A reference ID is a unique identifier or cookie used to reference which interchange this document is associated with.  The reference ID for the document interchange would typically be unique for an instance of a particular business process.
   *
   * @return Recipient reference ID.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getToReferenceID() throws BizException;


  /**
   * Returns state info set by the recipient. Process may be used to again refine the state of the interchange, by identifying the user account, process, or security context where the document originated, or is intended to be sent.  This is a further refinement of the <I>handle</I>.
   *
   * @return Process value.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getToProcess() throws BizException;

  /**
   * Returns state info set by the recipient. Handle provides additional handling or processing information that may be required by the application.  An example would be the handle for a functional module or step within a business process.  The handle is used as a further refinement of the reference ID.
   *
   * @return Handle value.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getToHandle() throws BizException;
  
  // message body
  /**
   * Returns an XML docuwent fragment representing the document body of
   * the original message.
   *
   * @return XML fragment for document body.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public String getBodyAsXML() throws BizException;

  /**
   * Returns an Object representing the document body. The actual class is dependent on the class implementing this interface. For example, the 
   * DOMIncomingMessage class will return the DOM node of the document body.
   *
   * @return Object representing document body.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public Object getBodyAsObject() throws BizException;
  /**
   * Returns an Object representing the document payload. 
   * The payload is the section between the &lt;body&gt; and &lt;/body&gt; tags.
   * The actual class is dependent on the class implementing this interface. 
   * For example, the DOMIncomingMessage class will return the DOM node of the document body.
   *
   * @return Object representing document payload.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public Object getPayloadAsObject() throws BizException;
  
  /**
   * Returns an OutgoingMessage object that can be used to respond
   * to the sender. i.e. the to/from fields are reversed.
   *
   * @return an Outgoing Message object representing a response to the sender.
   * @exception BizException unable to process the document due to parsing or IO failures.
   */
  public OutgoingMessage createResponse(String type, String name) throws BizException;
  
}
