NETLIB II

UC: the URL Connection

The model is based on the java URLConnection class: there is a sequence of operations you must do:

1. create an object supporting this interface (either directly with the appropriate protocol's URL Connection Factory object, or indirectly via the URL Connection Factory Registry),
2. call connect to do or start the operation,
3. If there is an output stream associated with this operatinon (e.g., an http or ftp PUT; an nntp POST), call getOS to get an output stream to which you can write, and then write,
4. If there is an expected response,(for most things there will be), call getIS to get an input stream from which the response may be read, and read that response.
5. release all of your handles.

Definition

package netscape.net;

import netscape.url.URL;
import netscape.types.Interval;

public abstract interface UC {
  public abstract void connect(Interval timeout) throws Exception;
  public abstract IS getIS() throws Exception;
  public abstract OS getOS() throws Exception;
  public abstract URL getURL();
  public abstract boolean is_secure();
  public abstract boolean is_proxyable();
  public abstract boolean is_network();
}

Interface Methods

• There is no creation method. This is an interface. The per-protocol objects that implement the URL Connection Factory interface UCF create objects that support this interface.
• connect

For connection-oriented operations (e.g., the typical http GET), this method initiates the connection: looks up the host name, opens the socket, sends the request, and parses the response headers. For atomic operations (e.g., the file protocol's MKDIR), that operation is done in this method.

The C signature of this method is:

void UC_connect(UC *self, PRIntervalTime timeout, JMCException **e);
• getIS

Get an input stream. After connect has established a connection, (and for operations involving an output stream, after all output data has been written), this method may be called to obtain an input stream from which the reply may be read. An exception will be thrown if connect has not yet been called, if an input stream has already been obtained and closed, or if an input stream is inappropriate for the operation.

The C signature of this method is:

IS *UC_getIS(UC *self, JMCException **e);
• getOS

Get an output stream. After connect has established a connection for an operation involving output data (e.g., an ftp PUT or nntp POST), this method may be called to obtain an output stream to which the output data may be written. An exception will be thrown if connecthas not yet been called, if an output stream has already been obtained and closed, or if an output stream is inappropriate for the operation or protocol.

The C signature of this method is:

OS *UC_getOS(UC *self, JMCException **e);
• getURL

This method simply returns another reference to the URL with which the underlying object was created.

The C signature of this method is:

URL *UC_getURL(UC *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

• is_secure

This method indicates whether or not the connection associated with this object is secure.

The C signature of this method is:

jbool UC_is__secure(UC *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

Note that JMC transformed the single underscore into a double underscore.

• is_proxyable

This method indicates whether or not the not-yet-connected operation may go through a proxy server. (Typically, this is constant for a given protocol.)

The C signature of this method is:

jbool UC_is__proxyable(UC *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

Note that JMC transformed the single underscore into a double underscore.

• is_network

This method indicates whether or not the protocol goes over a network connection. For example, file:// URL operations don't; http:// URL operations do.

The C signature of this method is:

jbool UC_is__network(UC *self, JMCException **e);

Note that although the java method signature does not specify that an exception may be thrown, due to the existance of java errors, an error may be reflected in this method's final argument.

Note that JMC transformed the single underscore into a double underscore.

Inherited Methods

C interface

#include "UC.h"

void UC_connect(UC *self, PRIntervalTime timeout, JMCException **e);
IS *UC_getIS(UC *self, JMCException **e);
OS *UC_getOS(UC *self, JMCException **e);
URL *UC_getURL(UC *self, JMCException **e);
jbool UC_is__secure(UC *self, JMCException **e);
jbool UC_is__proxyable(UC *self, JMCException **e);
jbool UC_is__network(UC *self, JMCException **e);

/* methods inherited from base JMC object interface */
void *UC_getInterface(UC *self, JMCInterfaceID id, JMCException **e);
void UC_addRef(UC *self, JMCException **e);
void UC_release(UC *self, JMCException **e);
jint UC_hashCode(UC *self, JMCException **e);
void *UC_clone(UC *self, JMCException **e);
const char *UC_toString(UC *self, JMCException **e);
void UC_finalize(UC *self, JMCException **e);