A Java Specification for the API

// Donna Bergmark - API for Linkable References - 2000/04/24

// Changes for the revision of 2000/03/23:
//   - dropped getReferences
//   - changed name from getBakedReferenceList to getReferenceList
//   - dropped field type and string from BibData
//   - dropped field type enumeration
//   - added enumerations for citation type and reference type
//   - moved the text fragments out of BibData 
// Changes for the revision of 2000-03-27:
//   - make a separate class type for creations, called Creation
//   - there may be more than one Surrogate objects that relate
//     to a given creation.  Each Surrogate object contains the URN
//     of its creation (which might just be a hash key, or index)
//   - added NOOP bodies to various methods
//   - changed Surrogate back into a CLASS so it could have fields
// Changes for the revision of 2000-04-05:
//   - getCurrentCitationList should return a Vector, not a Citation[]
// Changes for the revision of 2000-04-07 
//   - drop the RefEnum; type of reference should be implicitly clear
//   - add toString() methods to all objects just to be nice
//   - add a new method, toXML(), to the Creation object
//   - added accessor functions to the Reference object
//   - changed parameter type in Citation constructor from CiteEnum to int
//   - drop getID().  Method not related to the surrogate
// Changes for the revision of 2000-04-25:
//   - all API methods return a byte Stream containing structured 
//     data, i.e. an XML file describing the returned result
//   - Creation object's fields: MIMEfile text replaced by the
//     individual fields, for easier analysis and handling

public class Surrogate {

   private BibData myData;         // URN and metadata for this item
   private Reference[] refList;    // the references in this item
   private Vector knownCitations;  // Growing list of citations
   private String myURL;           // Network address of our item
   private MIMEfile localMetaData; // Original text fragments in this
				   // item corresponding to title, etc.

   // Constructor - make a surrogate for the item at this network address
   public Surrogate(String url) {}

   // Constructor - make a surrogate for the item at the local address
   // specified by the first string, with the network address in the
   // second string (needed for processing local copies of archives)
   public Surrogate ( String localURL, String netURL ) {}

   // getLinkedText returns the contents of the item along with live
   // link information, formatting, and structure as an XML file.  
   public byte[] getLinkedText () { return null; }

   // getReferenceList returns this item's references, in both original 
   // and in cannonical form with the Santa Fe 8 fields.
   public byte[] getReferenceList(){ return null; }

   // getCurrentCitationList returns the list of known citations of
   // this document.  
   public byte[] getCurrentCitationList () { return null; }

   // getMyData returns/Related the bibliographic data for this item, 
   // which includes this item's URN and OAMS metadata.
   public byte[] getMyData() { return null; }

   // getRefID implements Carl's "Is this one of your references?" question
   // as well as his "How do you reference this?" question
   // If the answer is no, getRefID returns null.
   public byte[] getRefID ( BibData b ) { return null; }

   // getCitationID implements Carl's "am I one of your citations?" question
   // If the answer is no, or unknown, getCitationID returns null
   public byte[] getCitationID ( BibData b ) { return null; }

   // getRelatedPapers is a placeholder for methods that return
   // co-cited, co-referenced papers of this one
   public BibData[] getRelatedPapers() { return null; }
   
   // dump out a string representation of this Surrogate
   public String toString() { "TBD"; }

   // UTILITY METHODS 

   // Given a Reference, construct from it a new Citation and return it
   // The CiteEnum type should be REFERENCE.
   protected static Citation buildCitation ( Reference r ) { }

   // Add this Citation to our knownCitations
   protected void addCitation ( Citation c ) { }

}

// A MIME file has a text file and a MIME type.  It is suitable for
// holding text/xml among other things.
public class MIMEfile {
   private String MIMEtype;
   private byte[] file;
   // Constructor
   public MIMEfile ( String m, byte[] f ) {}
   public String getMIMEtype()  {return "";};
   public byte[] getFile()      {return null;};  
   public String toString() { return ""; }
}

// Citation is a class which contains information about a creation known
// to have cited this document.  It contains as much information as can
// be gotten.  The context(s) is stored only for CiteEnums REFERENCE
// and RI (ResearchIndex).  REFERENCE means that the citation was discovered
// while processing an item in an open archive.
public class Citation {
   private BibData citationData;    // URI and XML of the citing creation
   private String context[];        // context in the citing document
   private CiteEnum how;            // how this item was cited
   // Constructor
   public Citation ( BibData bd, String[] c, int h ) {}
   public String[] getContext()    // return all the contexts of this citation
      { return new String[]{""};}
   public String toString() { return ""; } // returns XML
}

// CiteEnum is an enumeration of how we got this citation
public class CiteEnum {
   public static final int REFERENCE = 1;  // reference in analyzed paper
   public static final int SCI = 2;        // found out in the SCI
   public static final int RI = 3;         // from CiteSeer
   public String toString() { return ""; }
}

// Reference encapsulates data about a reference contained in a Creation
public class Reference {
   private BibData referenceData;  // URI and XML of the reference
   private int ordinalNumber;      // Which reference is this 1..N
   private String origRef;         // How the reference appeared in the text
   private String context[];       // Context(s) for this reference
   // Constructor 
   public Reference ( BibData bd, int n, String ref, String[] c ){}
   public BibData getDocID () {}
   public String[] getContexts() {}
   // Accessor functions - TBD
   public String toString() { return ""; } // returns XML
}

// Creation is the generic class containing information about a creation
// The fields are filled in on a best-effort basis.  (Used to be "BibData")
public class Creation {        
   private String URN;            // URI for this creation
   private int urnType;           // URN is a DOI? Synthesized?
   private String title;          // Title of the creation
   private Author[] authors;      // The author(s) of the creation
   private String data;           // The oams:Accession Date
   // Constructor returns an empty Creation object
   public Creation(){}
   // accessor functions for populating the BibData object
   public String getURN( return ""; ); 
   public int getUrnType () { return 0; }
   public void setUrn ( String u ){}
   public void setXML ( MIMEfile m ){}
   public String toString() { return ""; }
   public String toXML(String pad){} // returns XML
}

// BibData for this item can be used to get the associated creation
public class BibData {
   private String creationPointer;  // used to access the creation
   // constructor
   public BibData ( String cp ) {}
   // accessor functions
   public Creation getCreation() { return null; }
   public String toString() { return ""; }
}

// CiteRef is not immediately needed for a linked document, but might be
// useful in other contexts, say analyzing the citation database
public class CiteRef {
   public String sourceDocument;      // ID of citing document
   public String targetDocument;      // ID of cited document
   // constructor
   public CiteRef (String s, String t) {}
   // other methods TBD
   public String toString() { return ""; }
}