edu.wisc.ssec.mcidas.adde
Class AddeURLConnection

java.lang.Object
  java.net.URLConnection
      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