Description of differences between RAP 1.2 and RAP 1.1 (including Servlet API)

Last Updated - 99/11/22 NRD

Introduction

In the context of Prism (our DLI2 project) we discovered that the current RAP IDL (version 1.1) needed some massaging. Specifically, there were some security issues requiring some IDL tweaks, but in the course of designing those changes, we ended up taking a fresh look at the IDL. In particular, we were motivated to try to clarify some awkward constructs because we are passing the Fedora software to a growing number of collaborators.  We've changed very little functionally from RAP 1.1, but we feel the IDL and Servlet API are clearer now.

1. DisseminatorIDs are now URNs

If we think about how things evolved, we came to the point of realizing that every disseminator needed to be uniquely identified on the digital object. So, we created a Disseminator ID that is a concatenation of a signatureID and a descriptor. This is an awkward unique ID that seemed to evolve out of our previous design where the signatureID was supposed to be the unique id, but digital objects could have multiple disseminators with the same signature. Instead, why not let each Disseminator have its own unique ID? Given that condition, we would like the DisseminatorID to just be another URN instead of the concatenation of the SigID+descriptor. This is cleaner and also provides some optional benefits:

• A Disseminator can become a publicly registered interface if the repository owner wants to do this (unlike datastreams which have internal system-generated names). A URN format for a Disseminator does NOT mean the Disseminator HAS to be registered in the Handle System. It just means that it has the potential to be registered. In fact, some repositories may chose to never register a disseminator's URN.

To summarize, we want to make the DisseminatorID a URN because (1) a disseminator needs an unique ID anyway, (2) the current DisseminatorID is kind of a hack (trying to create a uniqueID out of the SigID+descriptor), (3) it can facilitate flexibility for web integration. For example, we might want to register the Disseminator's URN, and resolve it to the URL of a special Web page that lets the user talk to a particular "portal" on a DigitalObject (e.g., via CGI or Java Servlet talking RAP behind the scenes.) Again, some repositories might completely ignore this notion of a "registered" disseminator. Our interest is simply to transform the DisseminatorID into something with the potential to be used in a global resolver. The URN "format" is a single, unconcatenated string that can suit both our original needs and this new need.

Also, since it is useful to have a 'human readable' descriptor associated with each Disseminator, we retained this concept. We made it analogous to the descriptor associated with a Datastream.

2. The "Signature" terminology was somewhat confusing.

   We have our friendly SignatureDisseminator which lets us ultimately get a list of MethodSignatures. We would like this list of methods to be called a TypeSignature instead of a Signature. This is to prevent confusion for others, especially those security-minded folks whose first thought is that we mean a Digital Signature.

   We have also introduced the notion of the SignatureGenerator into the IDL to make things more parallel with what goes on with Servlets. So a SignatureDisseminator now returns a SignatureGenerator, which in turn will provide the TypeSignature. There is now a nice similarity between how SignatureGenerators and Servlets are expressed at the IDL level.

   To summarize the new terms:

   • a TypeSignature is a list of MethodSignatures describing a behavior interface for a Digital Object.
   • a SignatureGenerator is an executable interface that produces a TypeSignature.
   • a SignatureDisseminator is a bootstrap Disseminator that allows a client to obtain a SignatureGenerator via a RAP method call.

3. new inheritance structure for Disseminators

   We realized that SignatureDisseminators and ServletDisseminators have less in common with StandardDisseminators than RAP 1.1 implied. For example, SigDiss and SvDiss each require exactly ONE attachedDS, and it needs to be executable. Moreover, the notion of a "ServletID" for the Disseminator doesn't apply to SigDiss and SvDiss.

   Bonus: the IDL requires fewer kludgy constants in SigDiss and SvDiss.

4. Executable streams (such as Servlets) need an associated "name" (className) so security checking can be done before loading them into java VM.

   The practice of deriving the name from the URN was a temporary way to deal with this, and is also something that some servlet writers might not want to do. (For example, UVA has not done this.) Rather than force the URN to be parsable into the classname, we should require the servlet writer to provide the class name with the servlet when hooking it up in a Servlet DigitalObject. This is better security practice: not to load completely opaque streams of bytes into the virtual machine. Thus was born the new Executable interface in the IDL from which both RAP Servlet and SignatureGenerator interfaces inherit.

5. Methods pertaining to SignatureGenerator or Servlet information are now associated with the SignatureGenerator or Servlet IDL interfaces, instead of their respective Disseminators.

   For, example, when the ServletDisseminator used to say "GetAttachmentSpec" or "GetServletSignatureID" we always knew things were a bit quirky. The problem was that these were not attributes of the ServletDissemintor object, but of the Servlet executable. We made changes to clarify this and we think it gets rid of some of the weirdness around the Disseminators. The Disseminators now just disseminate either a Servlet or SignatureGenerator -- and those RAP interfaces allow you to get everything your heart desires about the Servlet or the TypeSignature, without over-encumbering the Disseminator. The ServletDisseminator and SignatureDisseminator now just allow setting and getting of attachedExecutableDS (which is a Servlet or a SignatureGenerator).

6. ServletAPI changes

   • package name is now "ServletAPI"
   • javadoc comments have been added
   • terminology matches that of IDL, with very few exceptions (which are noted)
   • other terminology changes for clarity
   • Exception class names
   • AttachmentRoleSpec: "requiredIndicator" instead of "optionalIndicator". We feel the intuitive question is "is it required?" not "is it optional?". The latter means you have to reason through a double negative to determine whether or not you must attach a DataStream.
   • we moved the list of returnMIMEtypes from the MethodSignature to a method in the Servlet interface (with a MethodSignature as a parameter so you get this info per implemented method). We can see that a client or user might want to know whether a RAP Dissemination will/can produce results of a particular MIME type, without actually performing the Dissemination. However, it seems wrong to have each MethodSignature indicate the possible MIME types that would be returned, as this could a) cause a proliferation of TypeSignatures that are the same except for return types and b) cause quicker obsolescence of TypeSignatures due to obsolescence of MIME types. It also seems wrong for the SignatureGenerator to indicate possible return types per method for the same reasons: this would still associate the return types for each method with the TypeSignature. Since a Servlet is an implementation of a TypeSignature, it seems more sensible to try to specify this information in the Servlet: the potential return types pertain to the implementation of each MethodSignature. This further makes sense as return types may be dependent on the MIME of the Attached DataStreams, and that is specified in the Servlet attachment specification. Have we overlooked something?

7. no more external datastreams ...

   This change is pending Christophe's approval.

Final note

We also noticed that there is a need to rethink what could be called the "architectural component metadata". For example, you can set a "Descriptor" for a DataStream when you create it, but you can never change it after it's been created. How many such "AC-metadata properties" are similarly constrained inappropriately by the current IDL? Moreover, there are a variety of "events" as defined in the IFLA FRBR model, such as "create" "update" and even "publish" for DigitalObjects and Repositories. We've noticed these problems but haven't solved them yet.