#include <orb.idl>

module RAP 
{

const string VERSION = "Version 1.1";

//**************************************************************
//  Forward declarations
//**************************************************************

interface Repository;
interface DigitalObject;
interface StandardDisseminator;
interface ServletDisseminator;
interface SignatureDisseminator;
interface AccessControl;

//***************************************************************
// TYPE DEFINITIONS
//***************************************************************

typedef string           MIME;
typedef string           URI;
typedef string           URN;
typedef sequence <octet> ByteStream;
typedef string           DataStreamID;
typedef URN              DigitalObjectID;
typedef URN              SignatureID; // URN of a signature DigitalObject 
typedef URN              ServletID;  // URN of a servlet DigitalObject
typedef ByteStream       SessionID; // For maintaining current context

typedef sequence <DataStreamID>     DataStreamIDList;
typedef sequence <DigitalObjectID>  DigitalObjectIDList;
typedef sequence <SignatureID>      DisseminatorTypeList;
typedef sequence <MIME>             MIMEList;

//****************************************************************
//  GENERAL REPOSITORY EXCEPTION
//****************************************************************

exception RepositorySystemError
{
   long ExceptionCode;
   string ExceptionString;
};

//******************************************************************
// CURRENT CONTEXT OF REPOSITORY
// Note: just a stub at this point
//******************************************************************

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

//******************************************************************
// DISSEMINATOR ID
//******************************************************************
struct DisseminatorID
{
   SignatureID signatureID;
   string disseminatorName;
};

typedef sequence <DisseminatorID> DisseminatorIDList;


//***************************************************************
//  REQUESTS
//***************************************************************

struct NamedTypedValue
{
    string name;
    any typedValue;
};

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

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

struct ServiceRequest
{
    URI           globalID;
    SignatureID   ServiceSignature;  
    ServletID     ServiceMechanism; 
    MethodRequest operation; 
};

enum RequestKind
{
    DISSEM_REQUEST,
    SERVICE_REQUEST
};

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

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

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

enum WriteBytesMode
{
    APPEND,
    OVERWRITE
};

interface DataStreamBase
{
   DataStreamID      GetDataStreamID() raises (RepositorySystemError);
   MIME              GetMIMEType() raises (RepositorySystemError);
   DSKeyMetadata     GetKeyMetadata() raises (RepositorySystemError);
   AccessControl     GetAccessControl() raises (RepositorySystemError);  // AccessControl has array of policy service requests?
   ByteStream        GetStreamBytes(in long length, in long offset)raises (RepositorySystemError);
};

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

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


interface ExternalStream : StreamReference
{
    void             SetWriteRequest(in ServiceRequest writeRequest) raises (RepositorySystemError);
    ServiceRequest   GetWriteRequest() raises (RepositorySystemError);
 
    long             SetBytes(
                         in long bufferLength,
                         in long absoluteStreamOffset,
                         in WriteBytesMode mode,
                         in ByteStream buffer)
                         raises (RepositorySystemError);
};

enum DataStreamKind
{
    INTERNAL,
    REFERENCE,
    EXTERNAL
};

union DataStream switch(DataStreamKind)
{
    case INTERNAL  :  InternalStream stream;  // data source stored in DigitalObject
    case REFERENCE :  StreamReference  streamReference;  // a read-only reference to data outside the DigitalObject
    case EXTERNAL  :  ExternalStream externalstream;  // a read/write non-RAP data source 
                                                            // that is is managed via protocol extensibility
};

typedef sequence <DataStream> DataStreamList;

//**************************************************************
//  DISSEMINATION RESULT
//**************************************************************

struct ResultHolder
{
    MIME MIMEType;
    ByteStream resultData;
};

typedef sequence <ResultHolder> Dissemination;

//**************************************************************
// SIGNATURE
//**************************************************************

struct NamedType
{
    string name;
    TypeCode typecode;
};

struct MethodSignature
{
    string methodName;
    sequence <NamedType> parameterTypes;
    Dissemination resultType;  // awkward: null in context of signature
};

typedef sequence <MethodSignature> Signature;

//**************************************************************
// SERVLET
//************************************************************** 

struct Servlet
{
    MIME MIMEType;  // type of executable
    ByteStream servletStream;
};

//************************************************************
// 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 one or more
// DataStreams to a Disseminator
//********************************************

struct AttachedDataStream
{
    string attachmentRoleName;
    DataStream associatedDataStream; // the DataStream assigned to a "role"
};

typedef sequence <AttachedDataStream> AttachedDataStreamList;

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

interface StandardDisseminator
{
    DisseminatorID          GetDisseminatorID()  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 
//************************************************
struct Ordinality
{
    long min;
    long max;
};

struct AttachmentRoleSpec
{
    string attachmentRoleName;  // a logical name that indicates the "role" 
                                // that a DataStream will play for a servlet
    boolean  optionalIndicator; // true if attaching DataStream to this "role" is optional
    Ordinality ordinality;  // number of DataStreams that can be attached to this "role"
    MIMEList MIMETypes;      // acceptable MIMEType for DataStream(s) attached to this "role"
};

typedef sequence<AttachmentRoleSpec> AttachmentSpec;

struct  AttachmentDef
{
    string encoding;         // e.g., "XML DTD"
    ByteStream  definition;  // an optional, encoded version of the AttachmentSpec,
                             // possibly with more detail
};

interface ServletDisseminator : StandardDisseminator
{
   const string DISSEMINATOR_ID_SIGNATURE_ID = "SERVLET_DISSEMINATOR";
   const string DISSEMINATOR_ID_DISSEMINATOR_NAME = "SERVLET";
   const string ATTACHMENT_NAME = "SERVLET";
   
   SignatureID      GetServletSignatureID() raises (RepositorySystemError);
   string           GetServletDescription() raises (RepositorySystemError);
   Servlet          GetServlet() raises (RepositorySystemError);
   AttachmentSpec   GetAttachmentSpecification() raises (RepositorySystemError);
   AttachmentDef    GetAttachmentDefinition() raises (RepositorySystemError);
};

//************************************************
// SignatureDisseminator 
//***********************************************

interface SignatureDisseminator : StandardDisseminator
{
   const string DISSEMINATOR_ID_SIGNATURE_ID = "SIGNATURE_DISSEMINATOR";
   const string DISSEMINATOR_ID_DISSEMINATOR_NAME = "SIGNATURE"; 
   const string ATTACHMENT_NAME = "SIGNATURE";

   Signature GetSignature()    raises (RepositorySystemError);
   string    GetSignatureDescription() raises (RepositorySystemError);
};

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

struct DOKeyMetadata // administrative attributes for DigitalObject
{
    string dateCreated;
    string dateLastRevised;
};

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

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

   // Extensible Access Methods
   DisseminatorTypeList ListDisseminatorTypes() raises (RepositorySystemError);
   Signature            GetDisseminatorTypeMethods(
                            in SignatureID disseminatorType)
                            raises (RepositorySystemError);
   Dissemination        GetDissemination(
                            in DisseminatorID disseminatorID, 
                            in MethodRequest request)
                            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 ServletID servletID,
                            in DisseminatorKind enumKind) 
                            raises (RepositorySystemError);
    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)
//******************************************************************

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

}; // END OF MODULE RAP