connector.java

有关j2me的很好的例子可以研究一下

/*
 * @(#)Connector.java	1.7 01/08/15
 * Copyright (c) 1999-2001 Sun Microsystems, Inc. All Rights Reserved.
 *
 * This software is the confidential and proprietary information of Sun
 * Microsystems, Inc. ("Confidential Information").  You shall not
 * disclose such Confidential Information and shall use it only in
 * accordance with the terms of the license agreement you entered into
 * with Sun.
 *
 * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
 * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
 * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
 * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
 * THIS SOFTWARE OR ITS DERIVATIVES.
 */

package javax.microedition.io;

import java.io.*;
import com.sun.cldc.io.*;

import com.sun.midp.io.InternalConnector;

/**

 * This class is a placeholder for the static methods that are used 
 * for creating all the Connection objects.
 * <p>
 * The creation of Connections is performed dynamically by looking 
 * up a protocol implementation class whose name is formed from the 
 * platform name (read from a system property) and the protocol name
 * of the requested connection (extracted from the parameter string 
 * supplied by the application programmer.)
 *
 * The parameter string that describes the target should conform
 * to the URL format as described in RFC 2396.
 * This takes the general form:
 * <p>
 * <code>{scheme}:[{target}][{parms}]</code>
 * <p>
 * where <code>{scheme}</code> is the name of a protocol such as 
 * <i>http</i>}.
 * <p>
 * The <code>{target}</code> is normally some kind of network 
 * address, but protocols may regard this as a fairly flexible
 * field when the connection is not network oriented.
 * <p>
 * Any <code>{parms}</code> are formed as a series of equates 
 * of the form ";x=y".  Example: ";type=a".
 * <p>
 * An optional second parameter may be specified to the open 
 * function. This is a mode flag that indicates to the protocol 
 * handler the intentions of the calling code. The options here 
 * specify if the connection is going to be read (READ), written 
 * (WRITE), or both (READ_WRITE). The validity of these flag 
 * settings is protocol dependent. For instance, a connection 
 * for a printer would not allow read access, and would throw 
 * an IllegalArgumentException if this were attempted. If the
 * mode parameter is not specified, READ_WRITE is used by default.
 * <p>
 * An optional third parameter is a boolean flag that indicates
 * if the calling code can handle timeout exceptions. If this 
 * flag is set, the protocol implementation may throw an 
 * InterruptedIOException when it detects a timeout condition.
 * This flag is only a hint to the protocol handler, and it 
 * does not guarantee that such exceptions will actually be thrown. 
 * If this parameter is not set, no timeout exceptions will be 
 * thrown. The timeout period is not specified in the open call
 * because this is protocol specific. Protocol implementors can
 * either hardwire an appropriate value or read them from an
 * external source such as the system properties. 
 * <p>
 * Because connections are frequently opened just to gain access
 * to a specific input or output stream, four convenience 
 * functions are provided for this purpose.
 *
 * See also: {@link DatagramConnection DatagramConnection}
 * for information relating to datagram addressing
 *
 * @author  Nik Shaylor
 * @author  Roger Riggs
 * @version 01/08/15
 */

public class Connector {
    /**
     * Access mode READ.
     */
    public final static int READ  = 1;

    /**
     * Access mode WRITE.
     */
    public final static int WRITE = 2;

    /**
     * Access mode READ_WRITE.
     */
    public final static int READ_WRITE = (READ|WRITE);

    /**
     * Prevent instantiation
     */
    private Connector() {}

    /**
     * Create and open a Connection.
     *
     * @param name           The URL for the connection.
     * @return                 A new Connection object.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the requested connection
     * cannot be make, or the protocol type does not exist.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static Connection open(String name) throws IOException {
        return open(name, READ_WRITE);
    }

    /**
     * Create and open a Connection.
     *
     * @param name           The URL for the connection.
     * @param mode             The access mode.
     * @return                 A new Connection object.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the requested connection
     * cannot be make, or the protocol type does not exist.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static Connection open(String name, int mode)
	throws IOException {

        return open(name, mode, false);
    }

    /**
     * Create and open a Connection.
     *
     * @param name           The URL for the connection
     * @param mode             The access mode
     * @param timeouts         A flag to indicate that the caller
     * wants timeout exceptions
     * @return                 A new Connection object
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException if the requested connection
     * cannot be make, or the protocol type does not exist.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static Connection open(String name, int mode, boolean timeouts)
	throws IOException {

	return InternalConnector.open(name, mode, timeouts);
    }

    /**
     * Create and open a connection input stream.
     *
     * @param  name          The URL for the connection.
     * @return                 A DataInputStream.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the connection cannot
     * be found.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static DataInputStream openDataInputStream(String name)
	throws IOException {

        InputConnection con = 
	    (InputConnection)Connector.open(name, Connector.READ);

        try {
          return con.openDataInputStream();
        } finally {
          con.close();
        }
    }

    /**
     * Create and open a connection output stream.
     *
     * @param  name         The URL for the connection.
     * @return                 A DataOutputStream.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the connection cannot
     * be found.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static DataOutputStream openDataOutputStream(String name)
	throws IOException {

        OutputConnection con = 
	    (OutputConnection)Connector.open(name, Connector.WRITE);

        try {
          return con.openDataOutputStream();
        } finally {
          con.close();
        }
    }

    /**
     * Create and open a connection input stream.
     *
     * @param  name         The URL for the connection.
     * @return                 An InputStream.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the connection cannot
     * be found.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static InputStream openInputStream(String name)
	throws IOException {

        return openDataInputStream(name);
    }

    /**
     * Create and open a connection output stream.
     *
     * @param  name         The URL for the connection.
     * @return                 An OutputStream.
     *
     * @exception IllegalArgumentException If a parameter is invalid.
     * @exception ConnectionNotFoundException If the connection cannot
     * be found.
     * @exception IOException  If some other kind of I/O error occurs.
     */
    public static OutputStream openOutputStream(String name)
	throws IOException {

        return openDataOutputStream(name);
    }

}