// 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: TygpeSignatureIDs 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 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 // no more EXTERNAL
};
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, // order change
in long absoluteStreamOffset,
in WriteBytesMode mode)
raises (RepositorySystemError);
};
//*********************************************
// ReferenceStream
//*********************************************
interface ReferenceStream : DataStreamBase // was StreamReference
{
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; // was attachmentRoleName
// a name indicating the "role" one or more DataStreams will
// play for the Servlet
boolean requiredIndicator; // was optionalIndicator
// 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 // was ResultHolder
{
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 // was NamedType
{
// 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