Skip to content
Browse files

more documentation and idl included in dist dir

svn path=/bioperl-corba-client/trunk/; revision=22
  • Loading branch information...
1 parent 7936dde commit 36aba930be27d8fdc52fb86d791a82ca80bacb89 @hyphaltip hyphaltip committed May 23, 2000
Showing with 235 additions and 0 deletions.
  1. +5 −0 README
  2. +230 −0 biocorba.idl
View
5 README
@@ -44,3 +44,8 @@ Because the tests are dependant on a server being available it is
necessary that links or copies of the IOR files and biocorba.idl
are setup correctly.
+If you want to run the DB.t test (the only one currently), you will
+need to start the servers/seqdbsrv.pl in bioperl-corba-server or
+some other CORBA SeqDB server. You will need an IOR file called
+seqdbsrv.ior (see t/DB.t for more info) in the client root dir
+(bioperl-corba-client-0.1 in the dist case).
View
230 biocorba.idl
@@ -0,0 +1,230 @@
+
+
+// Notes on the IDL.
+//
+// This IDL is designed to be pretty uncontroversial and simple. I am
+// using very simple CORBA features, and so no valuetypes, any's,
+// const's all of which get implemented late in ORBs (if at all).
+//
+// This IDL is designed only for sequences and features. There is no
+// provision for other stuff - we need to start with the things we can
+// agree with and build on that.
+//
+// This IDL should work well as an internal IDL for an OMG compliant
+// server. The OMG specification leaves alot of the "magic" to the
+// server, including memory management etc, and also uses alot of
+// "standard" OMG types and services which generally do not come
+// with a standard free ORB. Hence the GNOME memory management
+// model and the simple iterators.
+//
+// <birney@ebi.ac.uk>
+//
+
+//
+// This comes directly from the GNOME bonoboo model.
+// It allows memory management via ref and unref calls.
+// The query_interface is not important for this case,
+// but here for completeness.
+//
+
+module GNOME {
+ interface Unknown {
+ void ref();
+ void unref();
+ Object query_interface(in string repoid);
+ };
+};
+
+//
+// These are the actual biological objects that we are interested
+// in. Nearly everything is an interface. It is not going to work
+// well across large internet connections, so don't use it for that.
+//
+
+// The org.Biocorba.Seqcore package is so we look good in Java.
+// Makes the C interface names waaaaay too long of course
+
+module org {
+ module Biocorba {
+ module Seqcore
+ // changed indentation to give us more space for the main text
+{
+
+ exception RequestTooLarge { string reason;
+ long suggested_size; };
+ // means you need to request a smaller number,
+ // ie, request only failed due to its size.
+
+ exception OutOfRange { string reason; }; // For when start/end points are out of range.
+ exception EndOfStream { }; // for end of streams
+ exception UnableToProcess { string reason; }; // All other errors
+
+ enum SeqType { PROTEIN,DNA,RNA };
+
+ // AnonymousSeq is just the sequence informaiton and *nothing else*
+ // including names
+
+ interface AnonymousSeq : GNOME::Unknown {
+ SeqType type(); // server has to at least *guess* the type.
+ long length();
+
+ // the entire sequence. Use max_request_length to find the max
+ // size allowed
+ string get_seq() raises (RequestTooLarge);
+
+ // gets a sub sequence. the start,end are in biological
+ // coordinates, ie, 1-2 are the first two bases
+ string get_subseq(in long start,in long end) raises (OutOfRange,
+ RequestTooLarge);
+ // This is to find the largest string that can be passed back
+ long max_request_length();
+ };
+
+ // Primary sequences are just the sequence information and enough to
+ // idenity information to process the sequence/store results/etc.
+
+ interface PrimarySeq : AnonymousSeq {
+
+ // three different id's which might be the same. The first,
+ // display id is what to use if a human uses it. The second,
+ // primary_id is what the implementation decides as the correct
+ // unique id for this sequence. (in alot of cases this will be
+ // accession number). The final one is the accession number which
+ // is the unique id in the biological database which it is from
+ // (this maybe the same as the primary_id, but might not). Yes -
+ // we do need all three ids.
+
+ string display_id(); // id to display to humans
+ string primary_id(); // id to use as a unique id for this
+ // sequence. in some cases it could be
+ // byte position/file munged into a string for example
+ string accession_number(); // The unique id (commonly called accession number) in
+ // the biological database this comes from, not the particular
+ // instance of the database for the implementation.
+
+ long version(); // potential (unstable) version number for the sequence. 0 for
+ // things that don't have a version number
+
+ };
+
+ // Represents streaming through a single database, eg over a fasta file
+ // Don't forget to deference objects once they are done
+ interface PrimarySeqIterator : GNOME::Unknown {
+ PrimarySeq next() raises (EndOfStream,UnableToProcess);
+ boolean has_more(); // returns 1 when next_seq will give an object
+ };
+
+ // Provides a database mainly for database searching. Can make new
+ // streams and can retrieve sequences from the database.
+ interface PrimarySeqDB : GNOME::Unknown {
+ string database_name(); // This is to identify databases by name
+ short database_version(); // version of the database
+ PrimarySeqIterator make_PrimarySeqIterator(); // makes a new iterator object.
+ PrimarySeq get_PrimarySeq(in string primary_id) raises (UnableToProcess); // Retrieves one sequence
+ };
+
+
+ // We need to be able to pass back additional structured information
+ // in some cases. This gives us a way of doing it without specifying
+ // the structure at compile time. Try not to abuse this...
+
+
+ // This is equivalent to a hash of arrays in perl
+ typedef sequence <string> stringList;
+ struct NameValueSet {
+ string name;
+ stringList values;
+ };
+
+ typedef sequence <NameValueSet> NameValueSetList;
+
+ // SeqFeatures are features on a sequence. This is GFF
+ // compatible.
+
+ interface SeqFeature : GNOME::Unknown {
+ string type(); // exon, repeat etc.
+ string source(); // source of the SeqFeature mainly for GFF compatibility
+ string seq_primary_id(); // This gives the primary sequence id this is linked to.
+ long start(); // start in biological coordinates (1 is the first base)
+ long end(); // end in biological coordinates (1-2 are the first two bases in a sequence)
+ short strand(); // -1,0,1. -1 means reverse, 0 means either, 1 means forward. Irrelevant for proteins
+ NameValueSetList qualifiers(); // additional structured information
+ boolean PrimarySeq_is_available(); // returns 1 if it does, 0 if not.
+ PrimarySeq get_PrimarySeq() raises ( UnableToProcess ); // the Sequence may or may not be there.
+ // implementors are free to choose
+ };
+
+ typedef sequence <SeqFeature> SeqFeatureList;
+
+ // We have to handle large numbers of features.
+ interface SeqFeatureIterator : GNOME::Unknown {
+ SeqFeature next() raises (EndOfStream,UnableToProcess);
+ boolean has_more();
+ };
+
+ // Yes we should inheriet of SeqFeature for more complex things. Please
+ // inheriet off SeqFeature for your favourtie feature extension!
+
+ // This is one heavy object, This should really be a number of
+ // coordinating objects underneath. Notice that the Seq object
+ // both inheriets from the PrimarySeq interface and also has-a
+ // PrimarySeq interface. This is deliberate so that clients can
+ // indicate when they really want to discard a complete sequence
+ // with features by freeing but still hold on to the original
+ // primary sequence.
+
+ // otherwise servers will have extremely large objects for every
+ // sequence in feature rich databases (bad).
+
+ interface Seq : PrimarySeq {
+ SeqFeatureList all_features() raises (RequestTooLarge);
+ SeqFeatureIterator all_features_iterator();
+
+ SeqFeatureList features_region(in long start,in long end)
+ raises (OutOfRange,UnableToProcess,RequestTooLarge);
+ SeqFeatureIterator features_region_iterator(in long start,in long end)
+ raises (OutOfRange,UnableToProcess);
+
+ long max_feature_request();
+
+ // This is put here so that clients can ask servers just for the
+ // sequence and then free the large, seqfeature containing sequence.
+ // It prevents a sequence with features having to stay in memory for ever.
+ PrimarySeq get_PrimarySeq();
+ };
+
+ typedef sequence <string> primaryidList;
+
+
+ interface SeqDB : PrimarySeqDB {
+ Seq get_Seq(in string primary_id) raises (UnableToProcess); // Retrieves one sequence
+ primaryidList get_primaryidList();
+ };
+
+ // this allows to get hold of an object which will represent
+ // accessible code on a particular server. Notice that we allow concepts
+ // like filenames here. If so wished, the server can throw an exception
+ // on all the filename code (eg, client is on a different machine to server!)
+
+
+ interface BioEnv {
+ // format can an empty string, in which case BioEnv server guesses/
+ // throws an exception, depending on what it feels like
+ PrimarySeqIterator PrimarySeqIterator_from_file(in string format,in string filename) raises (UnableToProcess);
+ PrimarySeq PrimarySeq_from_file(in string format,in string filename) raises (UnableToProcess);
+ Seq Seq_from_file(in string format,in string filename);
+
+ // version can be empty, in which case, assumme the latest version
+ SeqDB SeqDB_by_name(in string name,in string version);
+ };
+
+}; // end Seqcore module
+ }; // end Biocorba module
+}; // end org module
+
+
+
+
+
+
+

0 comments on commit 36aba93

Please sign in to comment.
Something went wrong with that request. Please try again.