/* 
    * Copyright (c) 2012, Fraunhofer-Gesellschaft
    * All rights reserved.
    * 
    * Redistribution and use in source and binary forms, with or without
    * modification, are permitted provided that the following conditions are
    * met:
    * 
    * (1) Redistributions of source code must retain the above copyright
   *     notice, this list of conditions and the disclaimer at the end.
   *     Redistributions in binary form must reproduce the above copyright
   *     notice, this list of conditions and the following disclaimer in
   *     the documentation and/or other materials provided with the
   *     distribution.
   * 
   * (2) Neither the name of Fraunhofer nor the names of its
   *     contributors may be used to endorse or promote products derived
   *     from this software without specific prior written permission.
   * 
   * DISCLAIMER
   * 
   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
   * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
   * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
   * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
   * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
   * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
   *  
   */
  package org.ogf.graap.wsag.api.rest;
  
  import javax.ws.rs.Consumes;
  import javax.ws.rs.DELETE;
  import javax.ws.rs.GET;
  import javax.ws.rs.POST;
  import javax.ws.rs.Path;
  import javax.ws.rs.Produces;
  import javax.ws.rs.core.MediaType;
  
  import org.apache.cxf.annotations.DataBinding;
  import org.apache.cxf.xmlbeans.XmlBeansDataBinding;
  import org.ogf.graap.wsag.api.exceptions.NegotiationException;
  import org.ogf.graap.wsag.api.exceptions.ResourceUnavailableException;
  import org.ogf.graap.wsag.api.exceptions.ResourceUnknownException;
  import org.ogf.schemas.graap.wsAgreement.negotiation.AdvertiseInputDocument;
  import org.ogf.schemas.graap.wsAgreement.negotiation.NegotiateInputDocument;
  import org.ogf.schemas.graap.wsAgreement.negotiation.NegotiateOutputDocument;
  import org.ogf.schemas.graap.wsAgreement.negotiation.NegotiationPropertiesDocument;
  import org.ogf.schemas.graap.wsAgreement.negotiation.TerminateInputDocument;
  
  /**
   * Interface definition of the RESTful agreement service.
   * 
   * @author owaeld
   */
  @DataBinding( XmlBeansDataBinding.class )
  public interface RestNegotiation
  {
  
      /**
       * Returns the context of this negotiation process.
       * 
       * @return the negotiation context
       * @throws ResourceUnknownException
       *             the remote resource is unknown
       * @throws ResourceUnavailableException
       *             the remote resource is unavailable
       */
      @GET
      @Path( "/NegotiationContext" )
      @Produces( MediaType.APPLICATION_XML )
      NegotiationPropertiesDocument getNegotiationContext()
          throws ResourceUnknownException, ResourceUnavailableException;
  
      /**
       * A negotiation instance supports zero or more templates that can be used to create negotiation offers.
       * In case of a negotiation process, these templates are a subset of the templates offered by an agreement
       * factory. Only these templates are returned for which a proper negotiation strategy is implemented. in
       * case of agreement re negotiation, a negotiation instance may return one ore more templates to bootstrap
       * the negotiation process.
       * 
       * @return the negotiable templates
       * @throws ResourceUnknownException
       *             the remote resource is unknown
       * @throws ResourceUnavailableException
       *             the remote resource is unavailable
       */
      @GET
      @Path( "/NegotiableTemplates" )
      @Produces( MediaType.APPLICATION_XML )
      NegotiationPropertiesDocument getNegotiableTemplates()
          throws ResourceUnknownException, ResourceUnavailableException;
  
      /**
      * Returns a history of exchanged offers in this negotiation process.
      * 
      * @return the offers exchanged in this negotiation
      * @throws ResourceUnknownException
      *             the remote resource is unknown
      * @throws ResourceUnavailableException
      *             the remote resource is unavailable
      */
     @GET
     @Path( "/NegotiationOffers" )
     @Produces( MediaType.APPLICATION_XML )
     NegotiationPropertiesDocument getNegotiationOffers()
         throws ResourceUnknownException, ResourceUnavailableException;
 
     /**
      * Negotiates a set of agreement offers.
      * 
      * @param offers
      *            the offers to negotiate
      * @return a set of counter offers
      * @throws NegotiationException
      *             an error occured processing the negotiation request
      * @throws ResourceUnknownException
      *             the remote resource is unknown
      * @throws ResourceUnavailableException
      *             the remote resource is unavailable
      */
     @POST
     @Consumes( MediaType.APPLICATION_XML )
     @Produces( MediaType.APPLICATION_XML )
     NegotiateOutputDocument negotiate( NegotiateInputDocument offers )
         throws NegotiationException, ResourceUnknownException, ResourceUnavailableException;
 
     /**
      * Advertises a set of negotiation offers.
      * 
      * @param offers
      *            the offers to advertise
      * @throws NegotiationException
      *             an error occured processing the negotiation request
      * @throws ResourceUnknownException
      *             the remote resource is unknown
      * @throws ResourceUnavailableException
      *             the remote resource is unavailable
      */
     @POST
     @Consumes( MediaType.APPLICATION_XML )
     void advertise( AdvertiseInputDocument offers )
         throws NegotiationException, ResourceUnknownException, ResourceUnavailableException;
 
     /**
      * Terminates the agreement if permitted.
      * 
      * @param reason
      *            the termination reason
      * 
      * @throws ResourceUnknownException
      *             the referenced resource does not exist
      * @throws ResourceUnavailableException
      *             the referenced resource is not available
      */
     @POST
     @Path( "/Operations/Terminate" )
     @Consumes( MediaType.APPLICATION_XML )
     void terminate( TerminateInputDocument reason )
         throws ResourceUnknownException, ResourceUnavailableException;
 
     /**
      * Destroys the agreement REST resource.
      * 
      * @throws ResourceUnknownException
      *             the referenced resource does not exist
      * @throws ResourceUnavailableException
      *             the referenced resource is not available
      */
     @DELETE
     void destroy() throws ResourceUnknownException, ResourceUnavailableException;
 }