/********************************************************************
* API for Servlets and SignatureGenerators in RAP
*  enabling extensible behaviors for RAP Digital Objects
* RAP - Repository Access Protocol
********************************************************************/
package ServletAPI;

/**
 * This interface must be implemented by all RAP Servlets.  
 * 
 * A RAP Servlet is an executable mechanism that implements the 
 * behavior interface described by a RAP TypeSignature, so a RAP
 * Servlet implements both this interface and the methods
 * disseminated as a TypeSignature by a SignatureGenerator executable.
 * 
 * For a Servlet executable file (e.g. a java class file or a jar
 * file implementing this interface) to become a functional RAP Digital 
 * Object, the executable must be put into a RAP Digital Object as a 
 * DataStream.  Next a single disseminator of type ServletDisseminator 
 * must be added to the RAP Digital Object.  Lastly, the DataStream
 * containing the Servlet executable must be attached to the 
 * ServletDisseminator with the SetServletExecutable() method.
 * 
 * @author Christophe Blanchi
 * @author Sandy Payette
 * @author Naomi Dushay
 **/
public interface Servlet
{
    /**
     * @return the URN (as a string) of the RAP Digital Object containing this
     *  Servlet.  In other words, this is the ID of the RAP Digital
     *  Object that disseminates this Servlet.
     **/
    public String GetServletID()
        throws ServletAPIException;
    
    /**
     * @return a brief description of the Servlet as a string
     **/
    public String GetServletDescriptor()
        throws ServletAPIException;

    /**
     * @return the URN (as a string) of the RAP Digital Object that can disseminate
     *  the TypeSignature that this Servlet implements.  In other words, this is the
     *  ID of the RAP Digital Object that disseminates the TypeSignature implemented 
     *  by this Servlet
     **/
    public String GetTypeSignatureID()
        throws ServletAPIException;

    /**
     * @return the Servlet's attachment specification as an array of
     *  AttachmentRoleSpecs
     **/
    public AttachmentRoleSpec[] GetAttachmentSpecification()
        throws ServletAPIException;

    /**
     * @return the Servlet's encoded attachment specification, if 
     * there is one.  If not, return something like: 
     *    new AttachmentDef("no encoded definition", new byte[0])   
     **/
    public AttachmentDef GetAttachmentDefinition()
        throws ServletAPIException;

    /**
     * This method provides data to the Servlet at runtime.
     * The Servlet assigns the passed DataStream to the passed roleName.  Note that
     * there may be more than one DataStream for a roleName:  in that case, this 
     * method is called multiple times with the same roleName, but different
     * DataStreams.
     * 
     * This method is not in the RAP IDL, as it only pertains to 
     * the Servlet at runtime.  StandardDisseminators have AttachedDataStreams;
     * these overt associations inform the StandardDisseminator
     * which DataStreams to associate with each role name for the Servlet
     * at runtime.  StandardDisseminators use Servlets as "target objects".
     *
     * @param roleName the Servlet attachment "role" name for 
     *   the passed DataStream
     * @param DSMIMEType the MIME type of the DataStream
     * @param DSByteStream the bytes of the DataStream as a java.io.InputStream
     * @exception AttachmentException when there is a problem attaching
     *   the passed DataStream to the role.
     **/
    public void SetDataStream(
            String roleName, 
            String DSMIMEType, 
            java.io.InputStream DSByteStream)
        throws AttachmentException, ServletAPIException;

    /**
     * NOTE:  This is a DRAFT of a working concept.
     *  The problem:  A client or user might want to know whether a
     *  RAP Disseminaton will/can produce results of a particular MIME
     *  type, without actually performing the Dissemination.
     *
     *  A difficulty:  Imagine a Servlet that returns 
     *  two MIMETypedStreams for a method.  Let's say one of these streams
     *  is some sort of text thing and one is some sort of image thing.  
     *  Do we want to indicate the possible MIMETypes for each individual
     *  stream?  Or, if there is some implied relationship between these unlike
     *  streams, do we want to encourage that the result be one (XML?) stream?
     *  We're not yet sure how to answer this question.  In the meantime, this
     *  method is provided as a draft of this concept. 
     *
     * This method has not been elevated to the IDL at this time.
     *
     * @param MethodSignature description of which TypeSignature method this 
     *   query refers to.
     * @return an array of strings, each containing a MIME type that could be
     *  returned by the indicated method of this Servlet
     **/
    public String[] GetValidResultTypeList(
            ServletAPI.MethodSignature MethodSignature)
        throws ServletAPIException;
}