// RAP - Repository Access Protocol
//   by Sandy Payette, Christophe Blanchi and Naomi Dushay

module RAP 
{

const string VERSION = "Version 1.2.1";

//***************************************************************
// forward declarations
//***************************************************************

interface Repository;
interface DigitalObject;
interface DataStreamBase;
interface InternalStream;
interface ReferenceStream;
interface DisseminatorBase;
interface StandardDisseminator;
interface ServletDisseminator;
interface SignatureDisseminator;
interface Executable;
interface Servlet;
interface SignatureGenerator;
interface AccessControl;

//***************************************************************
// type definitions
//***************************************************************

typedef sequence <octet> ByteStream;
typedef ByteStream SessionID;  // For maintaining current context
typedef string         MIME;
typedef string         URI;
typedef string         URN;
typedef string         DataStreamID;
typedef URN            DigitalObjectID;
typedef URN            DisseminatorID;  
typedef DisseminatorID TypeSignatureID;  //URN of a SignatureDiss
typedef DisseminatorID ServletID;        //URN of a ServletDiss

// Note:  TypeSignatureIDs and ServletIDs should be registered as
// URNs whenever they are intended to be used by another 
// DigitalObject.  DisseminatorIDs associated with
// StandardDisseminators should not be registered as URNs except 
// for use in a non-RAP Repository manner (e.g. if the
// disseminator is intended to be accessed via a URL)

typedef sequence <DataStreamID>    DataStreamIDList;
typedef sequence <DisseminatorID>  DisseminatorIDList;
typedef sequence <DigitalObjectID> DigitalObjectIDList;
typedef sequence <TypeSignatureID> TypeSignatureIDList;
typedef sequence <MIME>            MIMEList;

//***************************************************************
// Exceptions
//***************************************************************

exception RepositorySystemError  // General Repository Exception
{
   long ExceptionCode;
   string ExceptionString;
};

//***************************************************************
// Current Context of Repository  (future use - in development)
//***************************************************************

struct CurrentContext
{
   string userID;
   SessionID sessionID;
   string IPaddr;
};

//***************************************************************
// Requests  (for Disseminations and Reference DataStreams) 
//***************************************************************

struct NamedTypedValue
{
   string name;
   any typedValue;
};

struct MethodRequest
{
   string methodName;
   sequence <NamedTypedValue> parameters;
};

struct DisseminationRequest
{
   DigitalObjectID digitalObjectID;
   DisseminatorID  disseminatorID;
   MethodRequest   methodRequest;
};

struct ServiceRequest
{
   URI             globalID;
   TypeSignatureID typeSignatureID;  
   ServletID       servletID; 
   MethodRequest   methodRequest; 
};

enum RequestKind
{
   DISSEM_REQUEST,
   SERVICE_REQUEST
};

union StreamRequest switch(RequestKind)
{
   case DISSEM_REQUEST  : DisseminationRequest disseminationRequest;
   case SERVICE_REQUEST : ServiceRequest  serviceRequest;
};


//***************************************************************
// DATASTREAM
//***************************************************************

enum DataStreamKind
{
   INTERNAL,
   REFERENCE
};

union DataStream switch(DataStreamKind)
{
   case INTERNAL  :  InternalStream stream;  
          // data source stored in DigitalObject
   case REFERENCE :  ReferenceStream  referenceStream;  
          // a read-only reference to data outside the DigitalObject
};

typedef sequence <DataStream> DataStreamList;

struct DSKeyMetadata  
{
   MIME      MIMEType;
   string    descriptor;
   long      size;
   string    dateDeposited;
   string    dateLastRevised;
};

enum WriteBytesMode
{
   APPEND,
   OVERWRITE
};

//*********************************************
// DataStreamBase
//*********************************************

interface DataStreamBase
{
   DataStreamID      GetDataStreamID() raises (RepositorySystemError);
   MIME              GetMIMEType() raises (RepositorySystemError);
   DSKeyMetadata     GetKeyMetadata() raises (RepositorySystemError);
   ByteStream        GetStreamBytes(
                         in long length,
                         in long offset)
                           raises (RepositorySystemError);
};

//*********************************************
// InternalStream
//*********************************************

interface InternalStream : DataStreamBase
{ 
   long              SetBytes(
                         in long inputBufferLength,
                         in ByteStream inputBuffer,
                         in long absoluteStreamOffset,
                         in WriteBytesMode mode)
                           raises (RepositorySystemError);
};

//*********************************************
// ReferenceStream
//*********************************************

interface ReferenceStream : DataStreamBase
{
   void             SetReadRequest(
                        in StreamRequest readRequest) 
                          raises (RepositorySystemError);
   StreamRequest    GetReadRequest() raises (RepositorySystemError);   
};


//***************************************************************
// DISSEMINATOR
//***************************************************************

enum DisseminatorKind
{
   DISSEMINATOR_SERVLET,
   DISSEMINATOR_SIGNATURE,
   DISSEMINATOR_STANDARD
};

union Disseminator switch(DisseminatorKind)
{
   case DISSEMINATOR_SERVLET :
           ServletDisseminator servletDisseminator;
   case DISSEMINATOR_SIGNATURE : 
           SignatureDisseminator signatureDisseminator;
   case DISSEMINATOR_STANDARD : 
           StandardDisseminator standardDisseminator;
};

typedef sequence <Disseminator> DisseminatorList;

//*********************************************
// structure for attaching DataStream(s) to a StandardDisseminator
//*********************************************

struct AttachedDataStream
{
   string attachmentRoleName;
   DataStream associatedDataStream; 
};

typedef sequence <AttachedDataStream> AttachedDataStreamList;

//*********************************************
// structure for attaching an executable DataStream
//   to a ServletDisseminator or SignatureDisseminator
//*********************************************

struct AttachedExecutableDS
{
   string executableName;
             // for a java class DataStream, the class name
             // for a java jar DataStream, the "main" class name
   DataStream associatedDataStream;  
};

//*********************************************
// Attachment Specification and Definition (for Servlets)
//*********************************************

struct Ordinality
{
   long min;
   long max;
};

struct AttachmentRoleSpec
{
   string roleName;  
       // a name indicating the "role" one or more DataStreams will
       //  play for the Servlet
   boolean requiredIndicator; 
       // true if attaching DataStream(s) to this "role" is required
   Ordinality ordinality;  
       // number of DataStreams to be attached to this "role"
   MIMEList MIMETypes; 
       // acceptable MIMETypes for DataStream(s) attached to this "role"
};

typedef sequence <AttachmentRoleSpec> AttachmentSpec;

//*********************************************
// an optional, encoded version of the AttachmentSpec,
//   possibly with more detail
//*********************************************

struct AttachmentDef
{
   string encoding;         // e.g., "XML DTD"
   ByteStream definition;  
};

//***************************************************************
// Dissemination  (result of a MethodRequest on a Disseminator)
//***************************************************************

struct MIMETypedStream
{
   MIME MIMEType;
   ByteStream data;
};

typedef sequence <MIMETypedStream> Dissemination;

//*********************************************
// TypeSignature
//   A TypeSignature is a list of MethodSignatures. It describes a
//   behavior interface (a Disseminator Type) for a Digital Object.
//*********************************************

struct Domain
{
   string encoding;  
	// future use to facilitate multiple machine readable schemes
   string value; 
	// a representation per encoding of a single allowable value
	// or a range of allowable values for a parameter
};

struct ParameterDescription	
{
   // note:  the value of the parameter is not included here
   string name;
   TypeCode type;  // in the API, this is expressed as a java class
   string descriptor;
   sequence <Domain> domain;
	// the domain is used to indicate allowable parameter values
        //  as defined by the community creating the TypeSignature.
        //  This domain of values has a notion of fixity:  it will not
        //  vary for the life of the TypeSignature, nor with 
        //  implementations of the TypeSignature (i.e. Servlets).
        // the domain should be empty when no such allowable list of
        //  parameters is defined.
        // Example:  for "GetDCField(element)" the list of DC elements 
};

struct MethodSignature
{
   string methodName;
   sequence <ParameterDescription> parameters;
   Dissemination returnType;
	// returnType is not populated in the context of
	// a TypeSignature, but is included here because each
	// MethodSignature must have a Dissemination return type
};

typedef sequence <MethodSignature> TypeSignature;

//*********************************************
// Executable
//*********************************************

interface Executable
{
   string     GetExecutableName() raises (RepositorySystemError);
   MIME       GetMIMEType() raises (RepositorySystemError);
   ByteStream GetExecutable() raises (RepositorySystemError);
};

//********************************************* 
// SignatureGenerator
//   A SignatureGenerator is an executable mechanism 
//   that produces a TypeSignature in an interoperable format.
//********************************************* 

interface SignatureGenerator : Executable
{
   string        GetTypeSignatureDescriptor()
                     raises (RepositorySystemError);
   TypeSignature GetTypeSignature()
                     raises (RepositorySystemError);
};

//********************************************* 
// Servlet
//   A Servlet is an executable mechanism that implements 
//   behaviors defined by a TypeSignature
//********************************************* 

interface Servlet : Executable
{
   string          GetServletDescriptor() 
                       raises (RepositorySystemError);
   TypeSignatureID GetTypeSignatureID() 
                       raises (RepositorySystemError);
   AttachmentSpec  GetAttachmentSpecification() 
                       raises (RepositorySystemError);
   AttachmentDef   GetAttachmentDefinition() 
                       raises (RepositorySystemError);
};

//********************************************* 
// DisseminatorBase
//*********************************************

interface DisseminatorBase
{
   DisseminatorID GetDisseminatorID() raises (RepositorySystemError);
   string         GetDescriptor() raises (RepositorySystemError);
};

//*********************************************
// StandardDisseminator
//*********************************************

interface StandardDisseminator : DisseminatorBase
{
   TypeSignatureID        GetTypeSignatureID()
                                raises (RepositorySystemError);
   ServletID              GetServletID()
                                raises (RepositorySystemError);
   AttachedDataStreamList GetAttachedDataStreams() 
                                raises (RepositorySystemError);
   void                   SetAttachedDataStreams(
                              in AttachedDataStreamList attachmentList)
                                raises (RepositorySystemError);
   void                   DeleteAttachedDataStreams(
                              in AttachedDataStreamList attachmentList)
                                raises (RepositorySystemError);
};

//********************************************
// ServletDisseminator 
//   bootstrap Disseminator for Servlets
//********************************************

interface ServletDisseminator : DisseminatorBase
{
   // the attachedExecutable must implement the RAP Servlet
   // interface defined in the Servlet API

   void                 SetServletExecutable(
                            in AttachedExecutableDS attachedExecutable)
                                raises (RepositorySystemError);
   AttachedExecutableDS GetAttachedExecutableDS() 
                                raises (RepositorySystemError);
   Servlet              GetServlet() 
                                raises (RepositorySystemError);

   // this is the TypeSignatureID for this Bootstrap disseminator
   // when DigitalObject.ListDisseminatorTypes() is called
   const string TYPE_SIGNATURE_ID = "SERVLET_DISSEMINATOR"; 
};

//********************************************
// SignatureDisseminator 
//   bootstrap Disseminator for Signatures
//********************************************

interface SignatureDisseminator : DisseminatorBase
{
   // the attachedExecutable must implement the RAP 
   // SignatureGenerator interface defined in the Servlet API

   void                 SetSignatureGeneratorExecutable(
                            in AttachedExecutableDS attachedExecutable)
                                raises (RepositorySystemError);
   AttachedExecutableDS GetAttachedExecutableDS() 
                                raises (RepositorySystemError);
   SignatureGenerator   GetSignatureGenerator() 
                                raises (RepositorySystemError);

   // this is the TypeSignatureID for this Bootstrap disseminator
   // when DigitalObject.ListDisseminatorTypes() is called
   const string TYPE_SIGNATURE_ID = "SIGNATURE_DISSEMINATOR"; 
};


//***************************************************************
// DIGITAL OBJECT 
//***************************************************************

struct DOKeyMetadata 
{
   string dateCreated;
   string dateLastRevised;
};

interface DigitalObject 
{
   DigitalObjectID     GetDigitalObjectID() 
                             raises (RepositorySystemError);
   DOKeyMetadata       GetKeyMetadata()
                             raises (RepositorySystemError);

   TypeSignatureIDList ListDisseminatorTypes() 
                             raises (RepositorySystemError);

   // Public Access Methods
   DisseminatorIDList  ListDisseminatorIDs() 
                             raises (RepositorySystemError);
   TypeSignature       GetDisseminatorTypeSignature(
                           in DisseminatorID disseminatorID)
                             raises (RepositorySystemError);
   Dissemination       GetDissemination(
                           in DisseminatorID disseminatorID, 
                           in MethodRequest request)
                             raises (RepositorySystemError);

   // Structural Access Methods
   Disseminator        GetDisseminator(
                           in DisseminatorID disseminatorID)
                             raises (RepositorySystemError);
   DisseminatorList    GetDisseminators()      
                             raises (RepositorySystemError);
   DataStreamIDList    ListDataStreamIDs()  
                             raises (RepositorySystemError);
   DataStream          GetDataStream(
                           in DataStreamID dataStreamID)
                             raises (RepositorySystemError);
   DataStreamList      GetDataStreams()
                             raises (RepositorySystemError);

   // Factory Methods
   DataStream          CreateDataStream (
                           in MIME MIMEType,
                           in string descriptor,
                           in DataStreamKind dsKind) 
                             raises (RepositorySystemError);
   void                DeleteDataStream(
                           in DataStreamID dataStreamID) 
                             raises (RepositorySystemError);
   Disseminator        CreateDisseminator(
                           in DisseminatorID disseminatorID,
                           in string descriptor,
                           in TypeSignatureID typeSignatureID,
                           in ServletID servletID,
                           in DisseminatorKind enumKind) 
                             raises (RepositorySystemError);
         // typeSignatureID and servletID are ignored for creation
         // of SignatureDisseminators and ServletDisseminators
   void                DeleteDisseminator(
                           in DisseminatorID disseminatorID) 
                             raises (RepositorySystemError);
}; 


//***************************************************************
// REPOSITORY
//***************************************************************

interface Repository : DigitalObject 
{

   // Future:  Repository Key Metadata?

   string              GetVersion() // RAP version
                             raises (RepositorySystemError); 
   SessionID           GetSessionID(in string userID) 
                             raises (RepositorySystemError);
   CurrentContext      GetCurrentContext(in SessionID sessionID) 
                             raises (RepositorySystemError);

   // Access Methods
   long                VerifyDigitalObject(
                           in DigitalObjectID digitalObjectID) 
                             raises (RepositorySystemError);
   DigitalObjectIDList ListDigitalObjectIDs(
                           in string filter) 
                                // filter - simple string search on URN
                             raises (RepositorySystemError);
   DigitalObject       GetDigitalObject(
                           in DigitalObjectID digitalObjectID) 
                             raises (RepositorySystemError);

   // Factory Methods
   DigitalObject       CreateDigitalObject(
                           in DigitalObjectID digitalObjectID) 
                             raises (RepositorySystemError);
   void                DeleteDigitalObject(
                           in DigitalObjectID digitalObjectID) 
                             raises (RepositorySystemError);
}; 


//***************************************************************
// ACCESS CONTROL  (future use - in development)
//***************************************************************

interface AccessControl
{
   string GetAccessControlType() raises (RepositorySystemError);
};

}; // END OF MODULE RAP