[Biojava-l] IDL semi-finalised
Ewan Birney
birney@ebi.ac.uk
Fri, 11 Feb 2000 12:34:22 +0000
With Matt (from biojava) and Kim Rutherford (from Artemis) help we have a
semi-finalised IDL. The IDL is more java friendly and provides a real
"just-the-sequence" object, called AnonymousSeq., designed so that people
who want to declare methods that *just work on sequences* without any
other information can get hold of them.
[there were alot of other interesting discussions about iterators and
databases which I wont bore you with].
I have updated the bioperl-corba-server distribution to work with this
IDL, so there is one working server people can download.
I would like the three different projects to generate a number of clients
and servers to this IDL so that we can really start throwing objects
around between them. Once this has happened then we can re-evaluate the
IDL on this basis and provide a final, frozen, IDL.
I would also be interested then in recruiting a team to work on providing
a stable, java based bridge between this IDL and the OMG-BSA IDL. I think
this would be a great project for a infrastructure company who wanted to
show that it was serious about supporting free software. (that's a heavy
hint to some people on this list).
IDL below.
// 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();
};
}; // end Seqcore module
}; // end Biocorba module
}; // end org module
-----------------------------------------------------------------
Ewan Birney. Mobile: +44 (0)7970 151230
<birney@ebi.ac.uk>
-----------------------------------------------------------------