opendap.dap
Class DConnect

java.lang.Object
  extended by opendap.dap.DConnect

public class DConnect
extends java.lang.Object

This class provides support for common OPeNDAP client-side operations such as dereferencing a OPeNDAP URL, communicating network activity status to the user and reading local OPeNDAP objects.

Unlike its C++ counterpart, this class does not store instances of the DAS, DDS, etc. objects. Rather, the methods getDAS, etc. return instances of those objects.

Version:
$Revision: 23881 $
Author:
jehamby

Constructor Summary
DConnect(java.io.InputStream is)
          Creates an instance bound to an already open InputStream.
DConnect(java.lang.String urlString)
          Creates an instance bound to url which accepts compressed documents.
DConnect(java.lang.String urlString, boolean acceptDeflate)
          Creates an instance bound to url.
 
Method Summary
 java.lang.String CE()
          Returns the constraint expression supplied with the URL given to the constructor.
 void getBlobData(DataDDS dds, StatusUI statusUI)
          Opens the BLOB uRL in the DDS supplied and deserializes that binary content sent from the server cooresponding to the DDS.
 DAS getDAS()
          Returns the DAS object from the dataset referenced by this object's URL.
 DataDDS getData(StatusUI statusUI)
          Return the data object with no local constraint expression.
 DataDDS getData(java.lang.String CE, StatusUI statusUI)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 DataDDS getData(java.lang.String CE, StatusUI statusUI, BaseTypeFactory btf)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 DataDDS getDataDDX()
          Returns the DataDDS object from the dataset referenced by this object's URL.
 DataDDS getDataDDX(java.lang.String CE)
          Returns the DataDDS object from the dataset referenced by this object's URL.
 DataDDS getDataDDX(java.lang.String CE, BaseTypeFactory btf)
          Returns the DataDDS object from the dataset referenced by this object's URL.
 DataDDS getDataFromUrl(java.net.URL url, StatusUI statusUI, BaseTypeFactory btf)
           
 DDS getDDS()
          Returns the DDS object from the dataset referenced by this object's URL.
 DDS getDDS(java.lang.String CE)
          Returns the DDS object from the dataset referenced by this object's URL.
 DDS getDDX()
          Returns the DDS object from the dataset referenced by this object's URL.
 DDS getDDX(java.lang.String CE)
          Returns the DDS object from the dataset referenced by this object's URL.
 DataDDS getDDXData(StatusUI statusUI)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 DataDDS getDDXData(java.lang.String CE, StatusUI statusUI)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 DataDDS getDDXData(java.lang.String CE, StatusUI statusUI, BaseTypeFactory btf)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 DataDDS getDDXDataFromURL(java.net.URL url, StatusUI statusUI, BaseTypeFactory btf)
          Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE.
 ServerVersion getServerVersion()
          Returns the ServerVersion of the last connection.
 boolean isLocal()
          Returns whether a file name or InputStream is being used instead of a URL.
 void setServerVersion(int major, int minor)
           
 java.lang.String URL()
          Returns the URL supplied to the constructor.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DConnect

public DConnect(java.lang.String urlString)
         throws java.io.FileNotFoundException
Creates an instance bound to url which accepts compressed documents.

Parameters:
urlString - connect to this URL.
Throws:
java.io.FileNotFoundException - thrown if urlString is not a valid URL, or a filename which exists on the system.
See Also:
DConnect(String, boolean)

DConnect

public DConnect(java.lang.String urlString,
                boolean acceptDeflate)
         throws java.io.FileNotFoundException
Creates an instance bound to url. If acceptDeflate is true then HTTP Request headers will indicate to servers that this client can accept compressed documents.

Parameters:
urlString - Connect to this URL. If urlString is not a valid URL, it is assumed to be a filename, which is opened.
acceptDeflate - true if this client can accept responses encoded with deflate.
Throws:
java.io.FileNotFoundException - thrown if urlString is not a valid URL, or a filename which exists on the system.

DConnect

public DConnect(java.io.InputStream is)
Creates an instance bound to an already open InputStream.

Parameters:
is - the InputStream to open.
Method Detail

setServerVersion

public void setServerVersion(int major,
                             int minor)

isLocal

public final boolean isLocal()
Returns whether a file name or InputStream is being used instead of a URL.

Returns:
true if a file name or InputStream is being used.

CE

public final java.lang.String CE()
Returns the constraint expression supplied with the URL given to the constructor. If no CE was given this returns an empty String.

Note that the CE supplied to one of this object's constructors is "sticky"; it will be used with every data request made with this object. The CE passed to getData, however, is not sticky; it is used only for that specific request. This method returns the sticky CE.

Returns:
the constraint expression associated with this connection.

URL

public final java.lang.String URL()
Returns the URL supplied to the constructor. If the URL contained a constraint expression that is not returned.

Returns:
the URL of this connection.

getDAS

public DAS getDAS()
           throws java.net.MalformedURLException,
                  java.io.IOException,
                  ParseException,
                  DASException,
                  DAP2Exception
Returns the DAS object from the dataset referenced by this object's URL. The DAS object is referred to by appending `.das' to the end of a OPeNDAP URL.

Returns:
the DAS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DAS parser returned an error
DASException - on an error constructing the DAS
DAP2Exception - if an error returned by the remote server

getDDS

public DDS getDDS()
           throws java.net.MalformedURLException,
                  java.io.IOException,
                  ParseException,
                  DDSException,
                  DAP2Exception
Returns the DDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.dds' to the end of a OPeNDAP URL.

Returns:
the DDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

getDDS

public DDS getDDS(java.lang.String CE)
           throws java.net.MalformedURLException,
                  java.io.IOException,
                  ParseException,
                  DDSException,
                  DAP2Exception
Returns the DDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.dds' to the end of a OPeNDAP URL.

Returns:
the DDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

getDDX

public DDS getDDX()
           throws java.net.MalformedURLException,
                  java.io.IOException,
                  ParseException,
                  DDSException,
                  DAP2Exception
Returns the DDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.ddx' to the end of a OPeNDAP URL. The server should send back a DDX (A DDS in XML format) which will get parsed here (locally) and a new DDS instantiated using the DDSXMLParser.

Returns:
the DDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getDDX

public DDS getDDX(java.lang.String CE)
           throws java.net.MalformedURLException,
                  java.io.IOException,
                  ParseException,
                  DDSException,
                  DAP2Exception
Returns the DDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.ddx' to the end of a OPeNDAP URL. The server should send back a DDX (A DDS in XML format) which will get parsed here (locally) and a new DDS instantiated using the DDSXMLParser.

Parameters:
CE -
Returns:
the DDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.net.MalformedURLException
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getDataDDX

public DataDDS getDataDDX()
                   throws java.net.MalformedURLException,
                          java.io.IOException,
                          ParseException,
                          DDSException,
                          DAP2Exception
Returns the DataDDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.ddx' to the end of a OPeNDAP URL. The server should send back a DDX (A DDS in XML format) which will get parsed here (locally) and a new DDS instantiated using the DDSXMLParser.

Returns:
the DataDDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getDataDDX

public DataDDS getDataDDX(java.lang.String CE)
                   throws java.net.MalformedURLException,
                          java.io.IOException,
                          ParseException,
                          DDSException,
                          DAP2Exception
Returns the DataDDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.ddx' to the end of a OPeNDAP URL. The server should send back a DDX (A DDS in XML format) which will get parsed here (locally) and a new DDS instantiated using the DDSXMLParser.

Parameters:
CE - The constraint expression to use for this request.
Returns:
the DataDDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getDataDDX

public DataDDS getDataDDX(java.lang.String CE,
                          BaseTypeFactory btf)
                   throws java.net.MalformedURLException,
                          java.io.IOException,
                          ParseException,
                          DDSException,
                          DAP2Exception
Returns the DataDDS object from the dataset referenced by this object's URL. The DDS object is referred to by appending `.ddx' to the end of a OPeNDAP URL. The server should send back a DDX (A DDS in XML format) which will get parsed here (locally) and a new DDS instantiated using the DDSXMLParser.

Parameters:
CE - The constraint expression to use for this request.
btf - The BaseTypeFactory to build the member variables in the DDS with.
Returns:
the DataDDS associated with the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if an error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if an error returned by the remote server
See Also:
BaseTypeFactory

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getData

public DataDDS getData(java.lang.String CE,
                       StatusUI statusUI,
                       BaseTypeFactory btf)
                throws java.net.MalformedURLException,
                       java.io.IOException,
                       ParseException,
                       DDSException,
                       DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

Parameters:
CE - The constraint expression to be applied to this request by the server. This is combined with any CE given in the constructor.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

getDDXData

public DataDDS getDDXData(java.lang.String CE,
                          StatusUI statusUI,
                          BaseTypeFactory btf)
                   throws java.net.MalformedURLException,
                          java.io.IOException,
                          ParseException,
                          DDSException,
                          DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

This method uses the 2 step method for aquiring data from a server using a DDX and a BLOB. First, a DDX (an XML representation of a DDS) is requested. The DDX is parsed and a DataDDS is created. The DDX contains a URL that points to the servers BLOB service. The BLOB service returns only the serialized binary content of the DataDDS. The DataDDS then deserializes the BLOB and fills itself with data.

Parameters:
CE - The constraint expression to be applied to this request by the server. This is combined with any CE given in the constructor.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getBlobData

public void getBlobData(DataDDS dds,
                        StatusUI statusUI)
                 throws java.net.MalformedURLException,
                        java.io.IOException,
                        ParseException,
                        DDSException,
                        DAP2Exception
Opens the BLOB uRL in the DDS supplied and deserializes that binary content sent from the server cooresponding to the DDS.

This method is the 2nd step in the 2 step process for aquiring data from a server using a DDX and a BLOB. First, a DDX (an XML representation of a DDS) is requested. The DDX is parsed and a DataDDS is created. The DDX contains a URL that points to the servers BLOB service. The BLOB service returns only the serialized binary content of the DataDDS. The DataDDS then deserializes the BLOB and fills itself with data.

Parameters:
dds - The DDS containing the BLOB URL and into which the BLOB (serialized binary content) will be deserialized.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

getDDXDataFromURL

public DataDDS getDDXDataFromURL(java.net.URL url,
                                 StatusUI statusUI,
                                 BaseTypeFactory btf)
                          throws java.io.IOException,
                                 ParseException,
                                 DDSException,
                                 DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

This method uses the 2 step method for aquiring data from a server using a DDX and a BLOB. First, a DDX (an XML representation of a DDS) is requested. The DDX is parsed and a DataDDS is created. The DDX contains a URL that points to the servers BLOB service. The BLOB service returns only the serialized binary content of the DataDDS. The DataDDS then deserializes the BLOB and fills itself with data.

Parameters:
url - The complete URL of the dataset. Constraint Expression included.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
btf - The BaseTypeFactory to build the member variables in the DDS with.
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getDataFromUrl

public DataDDS getDataFromUrl(java.net.URL url,
                              StatusUI statusUI,
                              BaseTypeFactory btf)
                       throws java.net.MalformedURLException,
                              java.io.IOException,
                              ParseException,
                              DDSException,
                              DAP2Exception
Throws:
java.net.MalformedURLException
java.io.IOException
ParseException
DDSException
DAP2Exception

getData

public DataDDS getData(java.lang.String CE,
                       StatusUI statusUI)
                throws java.net.MalformedURLException,
                       java.io.IOException,
                       ParseException,
                       DDSException,
                       DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

Parameters:
CE - The constraint expression to be applied to this request by the server. This is combined with any CE given in the constructor.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

getDDXData

public DataDDS getDDXData(java.lang.String CE,
                          StatusUI statusUI)
                   throws java.net.MalformedURLException,
                          java.io.IOException,
                          ParseException,
                          DDSException,
                          DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

This method uses the 2 step method for aquiring data from a server using a DDX and a BLOB. First, a DDX (an XML representation of a DDS) is requested. The DDX is parsed and a DataDDS is created. The DDX contains a URL that points to the servers BLOB service. The BLOB service returns only the serialized binary content of the DataDDS. The DataDDS then deserializes the BLOB and fills itself with data.

Parameters:
CE - The constraint expression to be applied to this request by the server. This is combined with any CE given in the constructor.
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getData

public final DataDDS getData(StatusUI statusUI)
                      throws java.net.MalformedURLException,
                             java.io.IOException,
                             ParseException,
                             DDSException,
                             DAP2Exception
Return the data object with no local constraint expression. Same as getData("", statusUI).

Parameters:
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying this object's sticky CE, if any, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server
See Also:
getData(String, StatusUI,BaseTypeFactory)

getDDXData

public final DataDDS getDDXData(StatusUI statusUI)
                         throws java.net.MalformedURLException,
                                java.io.IOException,
                                ParseException,
                                DDSException,
                                DAP2Exception
Returns the `Data object' from the dataset referenced by this object's URL given the constraint expression CE. Note that the Data object is really just a DDS object with data bound to the variables. The DDS will probably contain fewer variables (and those might have different types) than in the DDS returned by getDDS() because that method returns the entire DDS (but without any data) while this method returns only those variables listed in the projection part of the constraint expression.

Note that if CE is an empty String then the entire dataset will be returned, unless a "sticky" CE has been specified in the constructor.

This method uses the 2 step method for aquiring data from a server using a DDX and a BLOB. First, a DDX (an XML representation of a DDS) is requested. The DDX is parsed and a DataDDS is created. The DDX contains a URL that points to the servers BLOB service. The BLOB service returns only the serialized binary content of the DataDDS. The DataDDS then deserializes the BLOB and fills itself with data.

Parameters:
statusUI - the StatusUI object to use for GUI updates and user cancellation notification (may be null).
Returns:
The DataDDS object that results from applying the given CE, combined with this object's sticky CE, on the referenced dataset.
Throws:
java.net.MalformedURLException - if the URL given to the constructor has an error
java.io.IOException - if any error connecting to the remote server
ParseException - if the DDS parser returned an error
DDSException - on an error constructing the DDS
DAP2Exception - if any error returned by the remote server

This class/method is associated with pre-release version of the DDX API. It is experimental and is subject to (significant) change.


getServerVersion

public final ServerVersion getServerVersion()
Returns the ServerVersion of the last connection.

Returns:
the ServerVersion of the last connection.