edu.wisc.ssec.mcidas.adde
Class AddeURLConnection

java.lang.Object
  extended by java.net.URLConnection
      extended by edu.wisc.ssec.mcidas.adde.AddeURLConnection

public class AddeURLConnection
extends URLConnection

This class extends URLConnection, providing the guts of the work to establish an ADDE network connection, put together a request packet, and initiate data flow. Connections for image data, image directories, grid data, grid directory, point source data, text, weather text, observational text and dataset information (McIDAS AGET, ADIR, GDIR, GGET, MDKS, TXTG, OBTG, WXTG and LWPR requests) are supported.

Author:
Tommy Jasmin, University of Wisconsin, SSEC, Don Murray, UCAR/Unidata, Tom Whittaker, SSEC/CIMSS, James Kelly, Australian Bureau of Meteorology
See Also:
McIDAS Programmer's Manual

 URLs must all have the following format:

   adde://host/request?keyword_1=value_1&keyword_2=value_2

 where request can be one of the following:

   datasetinfo - request for data set information (LWPR)
   griddirectory - request for grid directory information (GDIR)
   griddata - request for grid data (GGET)
   imagedata - request for data in AreaFile format (AGET)
   imagedirectory - request for image directory information (ADIR)
   pointdata - request for point data (MDKS)
   textdata - request to read a text file (TXTG) 
   wxtext   - request to read a weather text file (WTXG) 
   obtext   - request to read a observation text file (OBTG) 

 There can be any valid combination of the following supported keywords:

 -------for any request

   group=<groupname>         ADDE group name
   user=<user_id>            ADDE user identification
   proj=<proj #>             a valid ADDE project number
   trace=<0/1>               setting to 1 tells server to write debug 
                               trace file 
   version=                  ADDE version number, currently 1 except for
                             griddata requests
   debug=                    set to true to watch the printlns stream by
   compress=                 set to "gzip" if you want to use the GZIP
                             compression or "compress" if you want to use 
                             transfers in Unix compress format (You need to 
                             have the VisAD package if you want to support 
                             this.)  default = none.
   port=                     Socket port to connect on.  Overridden by
                             a port specified in the host 
                             (e.g., adde.ucar.edu:500)

 -------for images:

   descr=<descriptor>        ADDE descriptor name
   band=<band>               spectral band or channel number 
   mag=<lmag> <emag>         image magnification, postitive for blowup, 
                               negative for blowdown (default = 1, emag=lmag)
                               (imagedata only)
   latlon=<lat> <lon>        lat/lon point to center image on (imagedata only)
   linele=<lin> <ele> <type> line/element to center image on (imagedata only)
   place=<placement>         placement of lat/lon or linele points (center 
                               or upperleft (def=center)) (imagedata only)
   track<0>               tell the ADDE server not to track for this

   pos=<position>            request an absolute or relative ADDE position 
                               number.  May use <start> <end>  Default
                               for <end> is 0 if start<0, or =start otherwise.
   size=<lines> <elements>   size of image to be returned (imagedata only)
   unit=<unit>               to specify calibration units other than the 
                               default 
   spac=<bytes>              number of bytes per data point, 1, 2, or 4 
                               (imagedata only)
   doc=<yes/no>              specify yes to include line documentation 
                               with image (def=no) 
   nav=<lalo>                include the lat-lon navigation info and not the O&A.
   aux=<yes/no>              specify yes to include auxilliary information 
                               with image 
   time=<time1> <time2>      specify the time range of images to select
                               (def=latest image if pos not specified)
   day=<day>                 specify the day of the images to select
                               (def=latest image if pos not specified)
   cal=<cal type>            request a specific calibration on the image 
                               (imagedata only)
   id=<stn id>               radar station id 

 ------ for grids:

   descr=<descriptor>        ADDE descriptor name
   param=<param list>        parameter code list
   time=<model run time>     time in hhmmss format
   day=<model run day>       day in ccyyddd format
   lev=<level list>          list of requested levels (value or SFC, MSL 
                               or TRO)
   ftime=<forecast time>     valid time (hhmmss format) (use with fday)
   fday=<forecast day>       forecast day (ccyyddd)
   fhour=<forecast hours>    forecast hours (offset from model run time)
                                (hhmmss format)
   lat=<min lat> <max lat>   latitude bounding box (needs lon specified)
   lon=<min lon> <max lon>   longitude bounding box (needs lat specified)
   row=<min row> <max row>   row bounding box (needs col specified)
   col=<min col> <max col>   column bounding box (needs row specified)
   skip=<row> <col>          skip factors for rows and columns (def = 1 1)
   gpro=<pro>                grid projection (e.g. TANC)
   src=<s1> ... <s2>         list of grid sources (ETA, AVN, etc)
   drange=<btime> <etime> <inc>  range of primary days 
                                 that the grid represents (cannot use with 
                                 day=)
   frange=<btime> <etime> <inc>  range of forecast times 
                                 that the grid represents (cannot use with
                                 fhour=, fday= or ftime=)
   trange=<btime> <etime> <inc>  range of primary times 
                                 that the grid represents (cannot use with time=)
   num=<max>                 maximum number of grids (nn) to return (def=1)

 ------ for point data:

   descr=<descriptor>        ADDE descriptor name
   pos=<position>            request an absolute or relative ADDE 
                               position number
   select=<select clause>    to specify which data is required
   param=<param list>        what parameters to return
   num=<max>                 maximum number of obs to return
   
 ------ for text data:

   descr=<descriptor>        ADDE descriptor name 
                             (may also be "descr=FILE=filename")
   file=<filename>           name of text file to read

 ------ for weather text data:

   group=<group>         weather text group (default= RTWXTEXT)
   prod=<product>        predefind product name
   apro=<val1 .. valn>   AFOS/AWIPS product headers to match (don't 
                         use with wmo keyword
   astn=<val1 .. valn>   AFOS/AWIPS stations to match
   wmo= <val1 .. valn>   WMO product headers to match (don't 
                         use with apro keyword
   wstn=<val1 .. valn>   WMO stations to match
   day=<start end>       range of days to search
   dtime=<numhours>      maximum number of hours to search back (def=96)
   match=<match strings> list of character match strings to find from text
   num=<num>             number of matches to find (def=1)

 ------ for observational text data:

   group=<group>         weather text group (default= RTWXTEXT)
   descr=<descriptor>    weather text subgroup (default=SFCHOURLY)
   id=<id1 id2 ... idn>  list of station ids
   co=<co1 co2 ... con>  list of countries
   reg=<reg1 reg2..regn> list of regions
   newest=<day hour>     most recent time to allow in request 
                         (def=current time)
   oldest=<day hour>     oldest observation time to allow in request
   type=<type>           numeric value for the type of ob
   nhours=<numhours>     maximum number of hours to search
   num=<num>             number of matches to find (def=1)

 -------------------------------------------------------------------------
 The following keywords are required:

   group 
   descr (except datasetinfo)

 These are case sensitive.  If you prefer to have them automatically upcased,
 you can supply a system property on the command line for your application:

     -Dadde.auto-upcase=true

 or add the "auto-upcase=true" keyword to the URL

 An example URL for images might look like:

   adde://viper/imagedata?group=gvar&band=1&user=tjj&proj=6999&version=1
   
 

Field Summary
static int ADIR
          ADIR request type
static int AGET
          AGET request type
static int DEFAULT_PORT
          default port transfers
static int DEFAULT_PROJ
          The default number of elements for an image request
static String DEFAULT_USER
          The default user id
static int GDIR
          GDIR request type
static int GGET
          GGET request type
static int LWPR
          LWPR request type
static int MDKS
          MDKS request type
static int OBTG
          OBTG request type
static int TXTG
          TXTG request type
static int VERSION_1
          ADDE Version 1 indicator
static int WTXG
          WTXG request type
 
Fields inherited from class java.net.URLConnection
allowUserInteraction, connected, doInput, doOutput, ifModifiedSince, useCaches
 
Method Summary
 void connect()
          Establishes an ADDE connection using the URL passed to the constructor.
 StringBuffer decodeLWPRString(String uCmd)
          Decode the ADDE request for data set information.
 StringBuffer decodeOBTGString(String uCmd)
          Decode the ADDE request for a weather observation text.
 StringBuffer decodeTXTGString(String uCmd)
          Decode the ADDE request for a text file.
 StringBuffer decodeWTXGString(String uCmd)
          Decode the ADDE request for a weather text.
 DataInputStream getDataInputStream()
          returns a reference to DataInputStream established in connect().
 int getInitialRecordSize()
          Return the number of bytes being sent by the server for the first record.
 InputStream getInputStream()
          returns a reference to InputStream established in connect().
 int getRequestType()
          Get the request type
 
Methods inherited from class java.net.URLConnection
addRequestProperty, getAllowUserInteraction, getConnectTimeout, getContent, getContent, getContentEncoding, getContentLength, getContentType, getDate, getDefaultAllowUserInteraction, getDefaultRequestProperty, getDefaultUseCaches, getDoInput, getDoOutput, getExpiration, getFileNameMap, getHeaderField, getHeaderField, getHeaderFieldDate, getHeaderFieldInt, getHeaderFieldKey, getHeaderFields, getIfModifiedSince, getLastModified, getOutputStream, getPermission, getReadTimeout, getRequestProperties, getRequestProperty, getURL, getUseCaches, guessContentTypeFromName, guessContentTypeFromStream, setAllowUserInteraction, setConnectTimeout, setContentHandlerFactory, setDefaultAllowUserInteraction, setDefaultRequestProperty, setDefaultUseCaches, setDoInput, setDoOutput, setFileNameMap, setIfModifiedSince, setReadTimeout, setRequestProperty, setUseCaches, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_USER

public static final String DEFAULT_USER
The default user id

See Also:
Constant Field Values

DEFAULT_PROJ

public static final int DEFAULT_PROJ
The default number of elements for an image request

See Also:
Constant Field Values

DEFAULT_PORT

public static final int DEFAULT_PORT
default port transfers

See Also:
Constant Field Values

VERSION_1

public static final int VERSION_1
ADDE Version 1 indicator

See Also:
Constant Field Values

AGET

public static final int AGET
AGET request type

See Also:
Constant Field Values

ADIR

public static final int ADIR
ADIR request type

See Also:
Constant Field Values

LWPR

public static final int LWPR
LWPR request type

See Also:
Constant Field Values

GDIR

public static final int GDIR
GDIR request type

See Also:
Constant Field Values

GGET

public static final int GGET
GGET request type

See Also:
Constant Field Values

MDKS

public static final int MDKS
MDKS request type

See Also:
Constant Field Values

TXTG

public static final int TXTG
TXTG request type

See Also:
Constant Field Values

WTXG

public static final int WTXG
WTXG request type

See Also:
Constant Field Values

OBTG

public static final int OBTG
OBTG request type

See Also:
Constant Field Values
Method Detail

connect

public void connect()
             throws IOException,
                    AddeURLException
Establishes an ADDE connection using the URL passed to the constructor. Opens a socket on the ADDE port, and formulates an ADDE image data request based on the file portion of URL.

An example URL might look like:

adde://viper.ssec.wisc.edu/image?group=gvar&band=1&mag=-8&version=1

Specified by:
connect in class URLConnection
Throws:
IOException
AddeURLException

getRequestType

public int getRequestType()
Get the request type

Returns:
type of request (ADIR, AGET, etc)

getInputStream

public InputStream getInputStream()
                           throws IOException
returns a reference to InputStream established in connect(). calls connect() if client has not done so yet.

Overrides:
getInputStream in class URLConnection
Returns:
InputStream reference
Throws:
IOException

getDataInputStream

public DataInputStream getDataInputStream()
                                   throws IOException
returns a reference to DataInputStream established in connect(). calls connect() if client has not done so yet.

Returns:
DataInputStream reference
Throws:
IOException

getInitialRecordSize

public int getInitialRecordSize()
Return the number of bytes being sent by the server for the first record.

Returns:
number of bytes send in the first record

decodeTXTGString

public StringBuffer decodeTXTGString(String uCmd)
Decode the ADDE request for a text file.
 there can be any valid combination of the following supported keywords:

   file=<filename>    the text file name on the server
   descr=<dataset>    the dataset name on the server
   group=<group>      the ADDE group name for this TEXT

 the following keywords are required:

   file or descr

 an example URL might look like:
   adde://viper/text?group=textdata&file=myfile.txt
   
 


decodeWTXGString

public StringBuffer decodeWTXGString(String uCmd)
Decode the ADDE request for a weather text.
 there can be any valid combination of the following supported keywords:

   group=<group>         weather text group (default= RTWXTEXT)
   prod=<product>        predefind product name
   apro=<val1 .. valn>   AFOS/AWIPS product headers to match (don't 
                         use with wmo keyword
   astn=<val1 .. valn>   AFOS/AWIPS stations to match
   wmo= <val1 .. valn>   WMO product headers to match (don't 
                         use with apro keyword
   wstn=<val1 .. valn>   WMO stations to match
   day=<start end>       range of days to search (def = current)
   dtime=<numhours>      maximum number of hours to search back (def=96)
   match=<match strings> list of character match strings to find from text
   num=<num>             number of matches to find (def=1)

 the following keywords are required:

   day  (should default to current, but there's a bug)
   apro, astn or wstn

 an example URL might look like:
   adde://viper/text?group=textdata&file=myfile.txt
   
 


decodeOBTGString

public StringBuffer decodeOBTGString(String uCmd)
Decode the ADDE request for a weather observation text.
 there can be any valid combination of the following supported keywords:


   group=<group>         weather text group (default= RTWXTEXT)
   descr=<descriptor>    weather text subgroup (default=SFCHOURLY)
   id=<id1 id2 ... idn>  list of station ids
   co=<co1 co2 ... con>  list of countries
   reg=<reg1 reg2..regn> list of regions
   newest=<day hour>     most recent time to allow in request 
                         (def=current time)
   oldest=<day hour>     oldest observation time to allow in request
   type=<type>           numeric value for the type of ob
   nhours=<numhours>     maximum number of hours to search
   num=<num>             number of matches to find (def=1)

 the following keywords are required:

   group
   descr
   id, co, or reg

 an example URL might look like:
  adde://adde.ucar.edu/obtext?group=rtwxtext&descr=sfchourly&id=kden&num=2
   
 


decodeLWPRString

public StringBuffer decodeLWPRString(String uCmd)
Decode the ADDE request for data set information.
 there can be any valid combination of the following supported keywords:

   group=<groupname>    ADDE group name
   type=<datatype>      ADDE data type.  Must be one of the following:
                             IMAGE, POINT, GRID, TEXT, NAV
                        the default is the IMAGE type.

 the following keywords are required:

   group

 an example URL might look like:
   adde://viper/datasetinfo?group=gvar&type=image