001    /*
002     * Copyright (c) OSGi Alliance (2002, 2008). All Rights Reserved.
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.osgi.service.io;
017    
018    import java.io.IOException;
019    
020    import javax.microedition.io.Connection;
021    
022    /**
023     * A Connection Factory service is called by the implementation of the Connector
024     * Service to create <code>javax.microedition.io.Connection</code> objects which
025     * implement the scheme named by <code>IO_SCHEME</code>.
026     * 
027     * When a <code>ConnectorService.open</code> method is called, the implementation
028     * of the Connector Service will examine the specified name for a scheme. The
029     * Connector Service will then look for a Connection Factory service which is
030     * registered with the service property <code>IO_SCHEME</code> which matches the
031     * scheme. The {@link #createConnection} method of the selected Connection
032     * Factory will then be called to create the actual <code>Connection</code>
033     * object.
034     * 
035     * @version $Revision: 5673 $
036     */
037    public interface ConnectionFactory {
038            /**
039             * Service property containing the scheme(s) for which this Connection
040             * Factory can create <code>Connection</code> objects. This property is of
041             * type <code>String</code> or <code>String[]</code>.
042             */
043            public static final String      IO_SCHEME       = "io.scheme";
044    
045            /**
046             * Create a new <code>Connection</code> object for the specified URI.
047             * 
048             * @param name The full URI passed to the <code>ConnectorService.open</code>
049             *        method
050             * @param mode The mode parameter passed to the
051             *        <code>ConnectorService.open</code> method
052             * @param timeouts The timeouts parameter passed to the
053             *        <code>ConnectorService.open</code> method
054             * @return A new <code>javax.microedition.io.Connection</code> object.
055             * @throws IOException If a <code>javax.microedition.io.Connection</code>
056             *         object can not not be created.
057             */
058            public Connection createConnection(String name, int mode, boolean timeouts)
059                            throws IOException;
060    }