glu
Class Glu

java.lang.Object
  extended byglu.Glu
All Implemented Interfaces:
java.lang.Runnable

public class Glu
extends java.lang.Object
implements java.lang.Runnable

Title: Java Glu client

Description: Simple Glu client allowing an application to query the nearest GLU registry both for URL resolutions and for retrieving Glu records.

The Glu system is a distributed Web resource registry. See the following examples to know the main functionnalities.

This class is java 1.1 compatible.

 Typical usage examples:

 1) You have to instantiate a glu java object which will find automatically
    which is the nearest Glu registry site:
          Glu glu = new Glu();

 2) a) You want to get the URL to the home page of the nearest ADS site:
          String ADSUrl = glu.getUrl("ADS.home");
    b) You want to get the URL to the nearest VizieR site to retrieve
       the excerpt of the USNOB catalog around M1 in VOTable format:
          String vizierUrl = glu.getUrl("VizFind","USNOB 'M 1'");
               or
          String params[] = { "USNOB","M 1" };
          String vizierUrl = glu.getUrl("VizFind",params);

 3) a) You want to get the result of a Simbad resolver call for 3C273:
          String coord = glu.getDocument("SimbadResolve","3C273");
    b) You want to open a browser (Explorer, Netscape or Mozilla - depending
       of your platform) with the result of the nearest "astro-ph" site
       concerning "GAIA" keyword:
          glu.showDocument("astro-ph","GAIA");

 4) a) You want to retrieve the list of all Glu record IDs (such as "ADS.home",
       "VizFind", "SimbadResolve", "astro-ph"...):
         String ids[] = glu.getIds();
    b) You want to retrieve the list of Glu record IDs concerning
       one specific Glu domain such as ASTRO:
         String ids[] = glu.getIds("ASTRO");

 5) You want to retrieve all Glu available domains (such as "ASTRO"...):
         String domains[] = glu.getDomains();

 6) a) You want to retrieve the full Glu record concerning Skyview direct
       image access in XML format:
        String xmlGluRecordOfSkyview = glu.getRecord("Skyview");
    b) You want to retrieve the full Glu dictionary in XML
        String xmlGluDictionary = glu.getRecords();

 7) FOR GLU ADVANCED USERS:
    You want to use the full Glu tag syntax:
       byte result[] = glu.resolve("<&cdsbib 1996&A...305L...5C|Biblio>");
          or
       InputStream = glu.openStream("<&cdsbib 1996&A...305L...5C|Biblio>");

 8) FOR GLU DEVELOPERS:
    You want to manipulate a full Glu record with the parsing facility
    provided by this class:
        String parfileGluRecord = glu.getRecord("WSimbad",Glu.PARFILE);
        Hashtable h = setRecordInHashtable(parfileGluRecord);
        String description = getField(h,"Description");
    The main "pre-defined" glu fields are:
        Description: One line description of the resource
        Url:         template of Url to access the resource
        Owner:       Institute/service having define this resource in Glu

 

Version:
1.1 (beta version) - may 2003
Author:
Fernique Pierre [CDS]

Field Summary
(package private) static java.lang.String BROWSER
           
private static java.lang.String[] BROWSERS
          Return the name of the netscape compatible browser on this machine
(package private) static int BUFSIZE
          Load fully a stream and return an array of bytes corresponding to the stream.
private  java.lang.String currentKey
           
private static java.lang.String DEFAULTGLUSITE
           
(package private) static boolean firstShowDoc
           
private  boolean flagTestGluSite
           
private  java.lang.String gluSite
           
private static java.lang.String HTTPGLUGATEWAYID
           
static int PARFILE
          Glu parfile syntax
static int SHORTPARFILE
          Glu parfile compact syntax
private  java.lang.Thread testGluSiteThread
           
static int XML
          Glu full XML syntax
 
Constructor Summary
Glu()
          Create GLU object with the fastest Glu site as remote resolver.
Glu(boolean testGluSite)
          Create GLU object with the fastest Glu site as remote resolver.
Glu(java.lang.String gluSite)
          Create GLU object with the fastest Glu site as remote resolver.
Glu(java.lang.String gluSite, boolean testGluSite)
          Create GLU object with the fastest Glu site as remote resolver.
 
Method Summary
 java.util.Hashtable buildDicAsHashtable(java.lang.String gluDic)
          Build a internal view of a set of glu records
private  java.net.URL buildUrlQuery(java.lang.String gluTag)
          return the Url query string for a Glu tag resolution
private  void endRecord(java.util.Hashtable h)
           
private  java.lang.String getBrowser()
           
 java.lang.String getDefaultGluSite()
          Return the default Glu site currently used See DEFAULTGLUSITE variable for an example.
private  byte[] getDic(java.lang.String idTemplate, java.lang.String param)
          Low level glu dictionary query
private  java.io.InputStream getDicStream(java.lang.String idTemplate, java.lang.String param)
          Open the stream for a Glu dictionary query
 java.lang.String getDocument(java.lang.String gluId)
          Glu call obtaining the document (result) describe by a glu Id.
 java.lang.String getDocument(java.lang.String gluId, java.lang.String params)
          Glu call obtaining the document (result) describe by a glu Id.
 java.lang.String getDocument(java.lang.String gluId, java.lang.String[] params)
          Glu call obtaining the document (result) describe by a glu Id.
 java.util.Vector getDomains()
          Provides the list of the "active" Glu domains.
 java.lang.String getField(java.util.Hashtable h, java.lang.String key)
          Return the first field associating to the "key"
 java.util.Vector getFields(java.util.Hashtable h, java.lang.String key)
          Return the list of fields associating to the "key"
 java.util.Vector getIds()
          Provides the list of all Glu ids
 java.util.Vector getIds(java.lang.String domain)
          Provides the list of Glu ids distributed in a specific domain
 java.lang.String getRecord(java.lang.String id)
          Provides XML record on resource designed by an Id
 java.lang.String getRecord(java.lang.String id, int syntax)
          Provides record on resource designed by an Id
 java.lang.String getRecords()
          Provides all glu Dictionary in XML
 java.lang.String getRecords(java.lang.String idTemplate)
          Provides XML records on resources designed by an Id template (with wilcards * and ?)
 java.lang.String getRecords(java.lang.String idTemplate, int syntax)
          Provides records on resources designed by an Id template (with wilcards * and ?)
 java.lang.String getUrl(java.lang.String gluId)
          Glu call to get the corresponding Url for a gludId.
 java.lang.String getUrl(java.lang.String gluId, java.lang.String params)
          Glu call to get the corresponding Url for a gludId.
 java.lang.String getUrl(java.lang.String gluId, java.lang.String[] params)
          Glu call to get the corresponding Url for a gludId.
private  java.util.Vector getVectorFromDicList(byte[] a)
          Builds a Vector from a list of IDs generated by a GLU daemon.
private  void init()
          Init Glu object
static java.lang.String joinParams(java.lang.String[] params)
          Create a parameter from an array of strings
 java.io.InputStream openStream(java.lang.String gluTag)
          Open the stream for a Glu tag query
private  int parseRecord(java.util.Hashtable h, char[] buf, int offset)
           
private  byte[] readFully(java.io.InputStream in)
           
 byte[] resolve(java.lang.String gluTag)
          Glu tag resolving.
 void run()
          Launch the determination of the nearest glu site and set it as the default.
private  void setBestGluSite()
          Determine the nearest GLU site HTTP "queriable" and set the corresponding default variable
 void setDefaultGluSite(java.lang.String u)
          Set the default Glu site
private  void setField(java.util.Hashtable h, char[] buf, int deb, int len)
           
private  void setKey(java.util.Hashtable h, char[] buf, int deb, int len)
           
 java.util.Hashtable setRecordInHashtable(java.lang.String r)
          Map a Glu record into a Hashtable of String (or Vector if necessary)
protected  void showDocument(java.lang.String gluId, java.lang.String params)
          Display Glu result of the "id" resource, with "param[]" list, in a browser.
protected  void showDocument(java.lang.String gluId, java.lang.String[] params)
          Display Glu result of the "id" resource, with "param[]" list, in a browser.
protected  void showDocument(java.lang.String gluId, java.lang.String[] params, java.applet.Applet applet, boolean flagProxy, java.lang.String window)
          Display Glu result of the "id" resource, with "param[]" list, in a browser.
protected  void showDocument(java.lang.String id, java.lang.String params, java.applet.Applet applet, boolean flagProxy, java.lang.String window)
          Display Glu result of the "id" resource, with "param[]" list, in a browser.
static java.lang.String[] splitParams(java.lang.String s)
          Splits a parameter string, eventually quoted by ' or " in a string array
private  void startRecord(java.util.Hashtable h, java.lang.String id)
          Internal methods to parse glu records (PARFILE|SHORTPARFILE FORMAT !!!)
private  int timeGluRespond(java.lang.String gluId)
          Return a time metric to contact an HTTP glu site.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

XML

public static final int XML
Glu full XML syntax

See Also:
Constant Field Values

PARFILE

public static final int PARFILE
Glu parfile syntax

See Also:
Constant Field Values

SHORTPARFILE

public static final int SHORTPARFILE
Glu parfile compact syntax

See Also:
Constant Field Values

DEFAULTGLUSITE

private static final java.lang.String DEFAULTGLUSITE
See Also:
Constant Field Values

HTTPGLUGATEWAYID

private static final java.lang.String HTTPGLUGATEWAYID
See Also:
Constant Field Values

gluSite

private java.lang.String gluSite

flagTestGluSite

private boolean flagTestGluSite

testGluSiteThread

private java.lang.Thread testGluSiteThread

BUFSIZE

static final int BUFSIZE
Load fully a stream and return an array of bytes corresponding to the stream.

See Also:
Constant Field Values

firstShowDoc

static boolean firstShowDoc

BROWSERS

private static final java.lang.String[] BROWSERS
Return the name of the netscape compatible browser on this machine


BROWSER

static java.lang.String BROWSER

currentKey

private java.lang.String currentKey
Constructor Detail

Glu

public Glu()
Create GLU object with the fastest Glu site as remote resolver. It uses the default glu site at Strasbourg until it has determined a better site (threaded)


Glu

public Glu(boolean testGluSite)
Create GLU object with the fastest Glu site as remote resolver. It uses Strasbourg/CDS default glu site until it has determined a better site if the flag "testGluSite" is true. It keeps the default Glu site otherwise.

Parameters:
testGluSite - true if the class has to determine a better Glu site than the default one

Glu

public Glu(java.lang.String gluSite)
Create GLU object with the fastest Glu site as remote resolver. It uses the specified glu site until it has determined a better site

Parameters:
gluSite - the first default glu site (url of the cgi, see DEFAULTGLUSITE for exemple)

Glu

public Glu(java.lang.String gluSite,
           boolean testGluSite)
Create GLU object with the fastest Glu site as remote resolver. It uses the specified glu site until it has determined a better site if the flag "testGluSite" is true. It keeps the default Glu site otherwise.

Parameters:
gluSite - the default glu site (url of the cgi, see DEFAULTGLUSITE for exemple)
testGluSite - true if the class has to determine a better Glu site than the default one
Method Detail

setDefaultGluSite

public void setDefaultGluSite(java.lang.String u)
Set the default Glu site

Parameters:
u - the cgi access of the glu site. See DEFAULTGLUSITE variable for an example.

getDefaultGluSite

public java.lang.String getDefaultGluSite()
Return the default Glu site currently used See DEFAULTGLUSITE variable for an example.


getUrl

public java.lang.String getUrl(java.lang.String gluId)
                        throws java.lang.Exception
Glu call to get the corresponding Url for a gludId.

Parameters:
gluId - the Glu tag to be resolved
Returns:
the result as a byte array
Throws:
java.lang.Exception

getUrl

public java.lang.String getUrl(java.lang.String gluId,
                               java.lang.String[] params)
                        throws java.lang.Exception
Glu call to get the corresponding Url for a gludId.

Parameters:
gluId - the Glu tag to be resolved
params - glu tags parameters as an array of strings
Returns:
the result as a byte array
Throws:
java.lang.Exception

getUrl

public java.lang.String getUrl(java.lang.String gluId,
                               java.lang.String params)
                        throws java.lang.Exception
Glu call to get the corresponding Url for a gludId.

Parameters:
gluId - the Glu tag to be resolved
params - glu tags parameters as a string, with blank separator and quotes if it is required ex: "USNOB 'HD 344'"
Returns:
the result as a byte array
Throws:
java.lang.Exception

getDocument

public java.lang.String getDocument(java.lang.String gluId)
                             throws java.lang.Exception
Glu call obtaining the document (result) describe by a glu Id.

Parameters:
gluId - the Glu tag to be resolved
Returns:
the result as a byte array
Throws:
java.lang.Exception

getDocument

public java.lang.String getDocument(java.lang.String gluId,
                                    java.lang.String[] params)
                             throws java.lang.Exception
Glu call obtaining the document (result) describe by a glu Id.

Parameters:
gluId - the Glu tag to be resolved
params - glu tags parameters as an array of strings
Returns:
the result as a byte array
Throws:
java.lang.Exception

getDocument

public java.lang.String getDocument(java.lang.String gluId,
                                    java.lang.String params)
                             throws java.lang.Exception
Glu call obtaining the document (result) describe by a glu Id.

Parameters:
gluId - the Glu tag to be resolved
params - glu tags parameters as a string, with blank separator and quotes if it is required ex: "USNOB 'HD 344'"
Returns:
the result as a byte array
Throws:
java.lang.Exception

resolve

public byte[] resolve(java.lang.String gluTag)
               throws java.lang.Exception
Glu tag resolving.

Parameters:
gluTag - the Glu tag to be resolved
Returns:
the result as a byte array
Throws:
java.lang.Exception

openStream

public java.io.InputStream openStream(java.lang.String gluTag)
                               throws java.lang.Exception
Open the stream for a Glu tag query

Parameters:
gluTag - the Glu tag to be resolved
Returns:
the corresponding stream
Throws:
java.lang.Exception

readFully

private byte[] readFully(java.io.InputStream in)
                  throws java.lang.Exception
Throws:
java.lang.Exception

getDomains

public java.util.Vector getDomains()
                            throws java.lang.Exception
Provides the list of the "active" Glu domains. (in which there is atleast one resource )published.

Returns:
domain list
Throws:
java.lang.Exception

getIds

public java.util.Vector getIds()
                        throws java.lang.Exception
Provides the list of all Glu ids

Throws:
java.lang.Exception

getIds

public java.util.Vector getIds(java.lang.String domain)
                        throws java.lang.Exception
Provides the list of Glu ids distributed in a specific domain

Parameters:
domain - Specific domain
Returns:
id list
Throws:
java.lang.Exception

getVectorFromDicList

private java.util.Vector getVectorFromDicList(byte[] a)
Builds a Vector from a list of IDs generated by a GLU daemon. Follows the format "X:domain/service/name\nX:domain/service/name\n


getRecords

public java.lang.String getRecords()
                            throws java.lang.Exception
Provides all glu Dictionary in XML

Returns:
XML Record list
Throws:
java.lang.Exception

getRecord

public java.lang.String getRecord(java.lang.String id)
                           throws java.lang.Exception
Provides XML record on resource designed by an Id

Parameters:
id - ID resource template: ex: VizFind
Returns:
XML Record
Throws:
java.lang.Exception

getRecords

public java.lang.String getRecords(java.lang.String idTemplate)
                            throws java.lang.Exception
Provides XML records on resources designed by an Id template (with wilcards * and ?)

Parameters:
idTemplate - ID resource template: ex: Viz*
Returns:
XML Record list
Throws:
java.lang.Exception

getRecord

public java.lang.String getRecord(java.lang.String id,
                                  int syntax)
                           throws java.lang.Exception
Provides record on resource designed by an Id

Parameters:
id - ID resource template: ex: VizFind
syntax - syntax for the result (XMM, PARFILE or SHORTPARFILE)
Returns:
Record
Throws:
java.lang.Exception

getRecords

public java.lang.String getRecords(java.lang.String idTemplate,
                                   int syntax)
                            throws java.lang.Exception
Provides records on resources designed by an Id template (with wilcards * and ?)

Parameters:
idTemplate - ID resource template: ex: Viz*
syntax - syntax for the result (XMM, PARFILE or SHORTPARFILE)
Returns:
Record list
Throws:
java.lang.Exception

getDic

private byte[] getDic(java.lang.String idTemplate,
                      java.lang.String param)
               throws java.lang.Exception
Low level glu dictionary query

Parameters:
idTemplate - Template of GLU id resources
param - parameters to constraint the query (see gludic parameters)
Throws:
java.lang.Exception

getDicStream

private java.io.InputStream getDicStream(java.lang.String idTemplate,
                                         java.lang.String param)
                                  throws java.lang.Exception
Open the stream for a Glu dictionary query

Parameters:
idTemplate - Template of GLU id resources
param - parameters to constraint the query (see gludic parameters)
Throws:
java.lang.Exception

buildUrlQuery

private java.net.URL buildUrlQuery(java.lang.String gluTag)
                            throws java.lang.Exception
return the Url query string for a Glu tag resolution

Parameters:
gluTag - the Glu tag to be resolved
Returns:
the Url string to do the remote resolution
Throws:
java.lang.Exception

joinParams

public static java.lang.String joinParams(java.lang.String[] params)
Create a parameter from an array of strings

Parameters:
params - array of strings
Returns:
parameter string (blank separator, eventually quoted)

splitParams

public static java.lang.String[] splitParams(java.lang.String s)
Splits a parameter string, eventually quoted by ' or " in a string array

Parameters:
s - parameter string, ex: "one 'two three' 'four \'or\' five'"
Returns:
string array or null if s is empty

showDocument

protected void showDocument(java.lang.String gluId,
                            java.lang.String[] params)
                     throws java.lang.Exception
Display Glu result of the "id" resource, with "param[]" list, in a browser. If the "flagProxy" is set, the real HTTP call will be done by the nearest GLU daemon instead of the local application.

Parameters:
params - array of strings for this glu id
Throws:
java.lang.Exception

showDocument

protected void showDocument(java.lang.String gluId,
                            java.lang.String params)
                     throws java.lang.Exception
Display Glu result of the "id" resource, with "param[]" list, in a browser. If the "flagProxy" is set, the real HTTP call will be done by the nearest GLU daemon instead of the local application.

Parameters:
params - parameter string for this glu id
Throws:
java.lang.Exception

showDocument

protected void showDocument(java.lang.String gluId,
                            java.lang.String[] params,
                            java.applet.Applet applet,
                            boolean flagProxy,
                            java.lang.String window)
                     throws java.lang.Exception
Display Glu result of the "id" resource, with "param[]" list, in a browser. If the "flagProxy" is set, the real HTTP call will be done by the nearest GLU daemon instead of the local application.

Parameters:
params - array of strings for this glu id
applet - applet reference if it the case, otherwise null
flagProxy - use the GLU site to call directly the HTTP resource
window - window name or null if any
Throws:
java.lang.Exception

showDocument

protected void showDocument(java.lang.String id,
                            java.lang.String params,
                            java.applet.Applet applet,
                            boolean flagProxy,
                            java.lang.String window)
                     throws java.lang.Exception
Display Glu result of the "id" resource, with "param[]" list, in a browser. If the "flagProxy" is set, the real HTTP call will be done by the nearest GLU daemon instead of the local application.

Parameters:
id - resource id
params - parameter string for this glu id
applet - applet reference if it the case, otherwise null
flagProxy - use the GLU site to call directly the HTTP resource
window - window name or null if any
Throws:
java.lang.Exception

getBrowser

private java.lang.String getBrowser()

setRecordInHashtable

public java.util.Hashtable setRecordInHashtable(java.lang.String r)
Map a Glu record into a Hashtable of String (or Vector if necessary)

Parameters:
r - the Glu recordas a paragraph
Returns:
the built hashtable

buildDicAsHashtable

public java.util.Hashtable buildDicAsHashtable(java.lang.String gluDic)
Build a internal view of a set of glu records

Parameters:
gluDic - excerpt of glu dictionary (PARFILE format)
Returns:
the glu dictionary as an hashtable of hashtables

getFields

public java.util.Vector getFields(java.util.Hashtable h,
                                  java.lang.String key)
Return the list of fields associating to the "key"

Parameters:
h - Hashtable representation of record
key -
Returns:
list of fields or null

getField

public java.lang.String getField(java.util.Hashtable h,
                                 java.lang.String key)
Return the first field associating to the "key"

Parameters:
h - Hashtable representation of record
key -
Returns:
the field or null

startRecord

private void startRecord(java.util.Hashtable h,
                         java.lang.String id)
Internal methods to parse glu records (PARFILE|SHORTPARFILE FORMAT !!!)


setKey

private void setKey(java.util.Hashtable h,
                    char[] buf,
                    int deb,
                    int len)

setField

private void setField(java.util.Hashtable h,
                      char[] buf,
                      int deb,
                      int len)

endRecord

private void endRecord(java.util.Hashtable h)

parseRecord

private int parseRecord(java.util.Hashtable h,
                        char[] buf,
                        int offset)

init

private void init()
Init Glu object


run

public void run()
Launch the determination of the nearest glu site and set it as the default.

Specified by:
run in interface java.lang.Runnable

setBestGluSite

private void setBestGluSite()
                     throws java.lang.Exception
Determine the nearest GLU site HTTP "queriable" and set the corresponding default variable

Throws:
java.lang.Exception

timeGluRespond

private int timeGluRespond(java.lang.String gluId)
                    throws java.lang.Exception
Return a time metric to contact an HTTP glu site. The test is done by querying the Glu record for J2000 data type

Parameters:
gluId - Glu Id of the glu site
Returns:
time metric (lower is better), negative values mean error
Throws:
java.lang.Exception