This interface provides an HTTP URL connection to clients.
The HttpURLConnection represents an Http URL connection between a client and a server. Instances of this component can be used both to read from and to write to the resource referenced by the URL. In general, creating a connection to a URL is a multistep process:
The setup parameters are modified using the following methods:
Each of the above set methods has a corresponding get method to retrieve the value of the parameter or general request property. The specific parameters and general request properties that are applicable are protocol specific.
The following methods are used to access the header fields and the contents after the connection is made to the remote object:
In the common case, all of the pre-connection parameters and general request properties can be ignored: the pre-connection parameters and request properties default to sensible values. For most clients of this interface, there are only two interesting methods: getInputStream and getObject, which are mirrored in the URL class by convenience methods.
More information on the request properties and header fields of an http connection can be found at:
http://www.ietf.org/rfc/rfc2068.txt
Connects the to the specified endpoint.
void connect
(
)
raises (NetComponents::TransportException);
This method will send all request and request headers to the server upon successfull connection. You have the option of sending additional data to the server by setting setDoOutput( true ) before connecting. If setDoOutput is true then you can use the SocketOutputStream interface to write data to the web server. Besure to set the Content-Length, Content-Type and/or any other headers that are required by the web server to support the content you send. Any headers you set to enable you to do input *must* be set before the connection occurs.
If setDoOutput is false, then connect will proceed to read the response headers from the web server. If setDoInput is true, then connect will return and allow you to read from the server using the SocketInputStream interface.
Disconnect from the server.
void disconnect
(
)
raises (NetComponents::TransportException);
Returns the value of the allowUserInteraction field for this object.
boolean getAllowUserInteraction
(
);
Retrieves the contents of this connection.
XDT::Binary getContent
(
)
raises (NetComponents::TransportException);
This method attempts to retrieve ALL the content as specified by the Content-Length: XYZ returned from the server. This may fail for large content lengths. You may wish to consider setting setDoInput( true ) and then reading the web server input in chunks.
Returns the value of the content-encoding header field.
XDT::StringValue getContentEncoding
(
);
return the content encoding of the resource that the URL references, or null if not known.
Returns the value of the content-length header field.
long getContentLength
(
);
return the content length of the resource that this connection's URL references, or -1 if the content length is not known.
Returns the value of the content-type header field.
XDT::StringValue getContentType
(
);
return the content type of the resource that the URL references, or null if not known.
Returns the value of the date header field.
XDT::TimeInstant getDate
(
);
return the sending date of the resource that the URL references, or 0 if not known.
Returns the default value of the allowUserInteraction field.
boolean getDefaultAllowUserInteraction
(
);
Ths default is "sticky", being a part of the static state of all Connections. This flag applies to the next, and all following Connections that are created.
return the default value of the allowUserInteraction field.
Returns the value of the default request property. Default request properties are set for every connection.
XDT::StringValue getDefaultRequestProperty
(
in string defaultRequestProperty
);
return the value of the default request property for the specified name.
Returns the default value of a Connection's useCaches flag.
boolean getDefaultUseCaches
(
);
Ths default is "sticky", being a part of the static state of all Connections. This flag applies to the next, and all following Connections that are created.
Returns the value of this connection's doInput flag.
boolean getDoInput
(
);
Returns the value of this Connection's doOutput flag.
boolean getDoOutput
(
);
Returns the error stream if the connection failed but the server sent useful data nonetheless. The typical example is when an HTTP server responds with a 404, which will cause a FileNotFoundException to be thrown in connect, but the server sent an HTML help page with suggestions as to what to do.
NetComponents::SocketInputStream getErrorStream
(
)
raises (NetComponents::TransportException);
This method will not cause a connection to be initiated. If there the connection was not connected, or if the server did not have an error while connecting or if the server did have an error but there no error data was sent, this method will return null. This is the default.
return an error stream if any, null if there have been no errors, the connection is not connected or the server sent no useful data.
Returns the value of the expires header field.
XDT::TimeInstant getExpiration
(
);
return the expiration date of the resource that this URL references, or 0 if not known.
Returns a boolean indicating whether or not HTTP redirects (3xx) should be automatically followed.
boolean getFollowRedirects
(
);
returns: true if HTTP redirects should be automatically followed, false if not.
Returns the value for the nth header field. It returns null if there are fewer than n fields.
XDT::StringValue getHeaderFieldByLong
(
in long index
);
This method can be used in conjunction with the getHeaderFieldName method to iterate through all the headers in the message.
n an index.
return the value of the nth header field.
Returns the name of the specified header field.
XDT::StringValue getHeaderFieldByString
(
in string name
);
Note: When HttpURLConnection reads the headers from the server it converts them to lowercase. The parameter name is also converted to lowercase for comparison. This is done to avoid inconsistencies between web servers that return different cases for header names.
name the name of a header field.
return the value of the named header field, or null if there is no such field in the header.
Returns the value of the named field parsed as date.
XDT::TimeInstant getHeaderFieldDate
(
in string name,
in XDT::TimeInstant defaultValue
);
This form of getHeaderField exists because some connection types (e.g., http-ng) have pre-parsed headers. Classes for that connection type can override this method and short-circuit the parsing.
name the name of the header field.
default a default value.
return the value of the field, parsed as a date. The value of the Default argument is returned if the field is missing or malformed.
Returns the value of the named field parsed as a number.
long getHeaderFieldInt
(
in string name,
in long defaultValue
);
This form of getHeaderField exists because some connection types (e.g., http-ng) have pre-parsed headers. Classes for that connection type can override this method and short-circuit the parsing.
name the name of the header field. default the default value.
return the value of the named field, parsed as an integer. The Default value is returned if the field is missing or malformed.
Returns the name for the nth header field.
XDT::StringValue getHeaderFieldName
(
in long index
);
n an index.
return the name for the nth header field, or null if there are fewer than n fields.
Returns the host (i.e. localhost) of this connection.
string getHost
(
);
Returns the value of this object's ifModifiedSince field.
XDT::TimeInstant getIfModifiedSince
(
);
Get the socket input stream for the connection
NetComponents::SocketInputStream getInputStream
(
)
raises (NetComponents::TransportException, NetComponents::IllegalAccessException);
Returns the name of the specified header field.
XDT::TimeInstant getLastModified
(
);
name the name of a header field.
return the value of the named header field, or null if there is no such field in the header.
Get the socket output stream for the connection
NetComponents::SocketOutputStream getOutputStream
(
)
raises (NetComponents::TransportException, NetComponents::IllegalAccessException);
Returns the port (i.e. 8081) of this connection.
string getPort
(
);
Returns the protocol (i.e. http or https) of this connection.
string getProtocol
(
);
Get the request method.
string getRequestMethod
(
);
Returns the value of the named general request property for this connection.
XDT::StringValue getRequestProperty
(
in string name
)
raises (NetComponents::InvalidPropertyException);
Gets HTTP response status. From responses like:
HTTP/1.0 200 OK HTTP/1.0 401 UnauthorizedExtracts the ints 200 and 401 respectively.
long getResponseCode
(
)
raises (NetComponents::TransportException);
returns -1 if none can be discerned from the response (i.e., the response is not valid HTTP). raises IOException if an error occurred connecting to the server.
Gets the HTTP response message, if any, returned along with the response code from a server. From responses like:
HTTP/1.0 200 OK HTTP/1.0 404 Not FoundExtracts the Strings "OK" and "Not Found" respectively.
XDT::StringValue getResponseMessage
(
)
raises (NetComponents::TransportException);
returns null if none could be discerned from the responses (the result was not valid HTTP). throws IOException if an error occurred connecting to the server.
Returns the URI (i.e. new.jpg) of this connection.
string getURI
(
);
Returns the value of this Connection's useCaches field.
boolean getUseCaches
(
);
Set the value of the allowUserInteraction field of this Connection.
void setAllowUserInteraction
(
in boolean allowUserInteraction
)
raises (NetComponents::IllegalAccessException);
allowuserinteraction the new value.
Sets the default value of the allowUserInteraction field for all future Connection objects to the specified value.
void setDefaultAllowUserInteraction
(
in boolean defaultAllowUserInteraction
);
<defaultAllowUserInteraction the new value.
Sets the default value of a general request property. When a Connection is created, it is initialized with these properties.
void setDefaultRequestProperty
(
in string prop,
in string value
)
raises (NetComponents::InvalidPropertyException, NetComponents::InvalidValueException);
prop the keyword by which the request is known (e.g., "accept").
value the value associated with the prop.
Sets the default value of the useCaches field to the specified value.
void setDefaultUseCaches
(
in boolean defaultUseCaches
);
defaultUseCaches the new value.
Sets the value of the doInput field for this connection to the specified value.
void setDoInput
(
in boolean doInput
)
raises (NetComponents::IllegalAccessException);
doInput the new value.
A connection can be used for input and/or output. Set the DoInput flag to true if you intend to use the connection for input, false if not. The default is true unless DoOutput is explicitly set to true, in which case DoInput defaults to false.
Sets the value of the doOutput field for this Connection to the specified value.
void setDoOutput
(
in boolean doOutput
)
raises (NetComponents::IllegalAccessException);
value the new value.
A connection can be used for input and/or output. Set the DoOutput flag to true if you intend to use the connection for output, false if not. The default is false.
Sets whether HTTP redirects (requests with response code 3xx) should be automatically followed. True by default.
void setFollowRedirects
(
in boolean followRedirects
);
Sets the value of the ifModifiedSince field of this Connection to the specified value.
void setIfModifiedSince
(
in XDT::TimeInstant ifModifiedSince
)
raises (NetComponents::IllegalAccessException);
value the new value.
Set the method for the URL request.
void setRequestMethod
(
in string method
)
raises (NetComponents::ProtocolException, NetComponents::IllegalAccessException);
ProtocolException if the method cannot be reset or if the requested method isn't valid for HTTP.
Sets the general request property.
void setRequestProperty
(
in string name,
in string value
)
raises (NetComponents::InvalidPropertyException, NetComponents::InvalidValueException, NetComponents::IllegalAccessException);
name the keyword by which the request is known (e.g., "accept").
value the value associated with it.
Set the connection information, this mimics the java.net.URLConnection constructor eg: http://localhost/file.html
void setURL
(
in string url
)
raises (NetComponents::IllegalAccessException);
Set the connection information, this mimics the java.net.URLConnection constructor Given the following URL: http://localhost/file.txt Results in machine_name: localhost port: 80 uri: /file.txt Given the following URL: http://localhost/file.txt&name1=value1;name2=value2 Results in machine_name: localhost port: 80 uri: /file.txt&name1=value1;name2=value2
void setURLByPart
(
in string machine_name,
in string port,
in string uri
)
raises (NetComponents::InvalidPropertyException, NetComponents::IllegalAccessException);
Sets the value of the useCaches field of this Connection to the specified value.
void setUseCaches
(
in boolean useCaches
)
raises (NetComponents::IllegalAccessException);
Some protocols do caching of documents. Occasionally, it is important to be able to "tunnel through" and ignore the caches (e.g., the "reload" button in a browser). If the UseCaches flag on a connection is true, the connection is allowed to use whatever caches it can. If false, caches are to be ignored.
The default value comes from DefaultUseCaches, which defaults to true.
Indicates if the connection is going through a proxy.
boolean usingProxy
(
);