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.*;
019
020 import javax.microedition.io.Connection;
021 import javax.microedition.io.Connector;
022
023 /**
024 * The Connector Service should be called to create and open
025 * <code>javax.microedition.io.Connection</code> objects.
026 *
027 * When an <code>open*</code> method is called, the implementation of the
028 * Connector Service will examine the specified name for a scheme. The Connector
029 * Service will then look for a Connection Factory service which is registered
030 * with the service property <code>IO_SCHEME</code> which matches the scheme. The
031 * <code>createConnection</code> method of the selected Connection Factory will
032 * then be called to create the actual <code>Connection</code> object.
033 *
034 * <p>
035 * If more than one Connection Factory service is registered for a particular
036 * scheme, the service with the highest ranking (as specified in its
037 * <code>service.ranking</code> property) is called. If there is a tie in ranking,
038 * the service with the lowest service ID (as specified in its
039 * <code>service.id</code> property), that is the service that was registered
040 * first, is called. This is the same algorithm used by
041 * <code>BundleContext.getServiceReference</code>.
042 *
043 * @version $Revision: 5673 $
044 */
045 public interface ConnectorService {
046 /**
047 * Read access mode.
048 *
049 * @see "javax.microedition.io.Connector.READ"
050 */
051 public static final int READ = Connector.READ;
052 /**
053 * Write access mode.
054 *
055 * @see "javax.microedition.io.Connector.WRITE"
056 */
057 public static final int WRITE = Connector.WRITE;
058 /**
059 * Read/Write access mode.
060 *
061 * @see "javax.microedition.io.Connector.READ_WRITE"
062 */
063 public static final int READ_WRITE = Connector.READ_WRITE;
064
065 /**
066 * Create and open a <code>Connection</code> object for the specified name.
067 *
068 * @param name The URI for the connection.
069 * @return A new <code>javax.microedition.io.Connection</code> object.
070 * @throws IllegalArgumentException If a parameter is invalid.
071 * @throws javax.microedition.io.ConnectionNotFoundException If the
072 * connection cannot be found.
073 * @throws IOException If some other kind of I/O error occurs.
074 * @see "javax.microedition.io.Connector.open(String name)"
075 */
076 public Connection open(String name) throws IOException;
077
078 /**
079 * Create and open a <code>Connection</code> object for the specified name and
080 * access mode.
081 *
082 * @param name The URI for the connection.
083 * @param mode The access mode.
084 * @return A new <code>javax.microedition.io.Connection</code> object.
085 * @throws IllegalArgumentException If a parameter is invalid.
086 * @throws javax.microedition.io.ConnectionNotFoundException If the
087 * connection cannot be found.
088 * @throws IOException If some other kind of I/O error occurs.
089 * @see "javax.microedition.io.Connector.open(String name, int mode)"
090 */
091 public Connection open(String name, int mode) throws IOException;
092
093 /**
094 * Create and open a <code>Connection</code> object for the specified name,
095 * access mode and timeouts.
096 *
097 * @param name The URI for the connection.
098 * @param mode The access mode.
099 * @param timeouts A flag to indicate that the caller wants timeout
100 * exceptions.
101 * @return A new <code>javax.microedition.io.Connection</code> object.
102 * @throws IllegalArgumentException If a parameter is invalid.
103 * @throws javax.microedition.io.ConnectionNotFoundException If the
104 * connection cannot be found.
105 * @throws IOException If some other kind of I/O error occurs.
106 * @see "<code>javax.microedition.io.Connector.open</code>"
107 */
108 public Connection open(String name, int mode, boolean timeouts)
109 throws IOException;
110
111 /**
112 * Create and open an <code>InputStream</code> object for the specified name.
113 *
114 * @param name The URI for the connection.
115 * @return An <code>InputStream</code> object.
116 * @throws IllegalArgumentException If a parameter is invalid.
117 * @throws javax.microedition.io.ConnectionNotFoundException If the
118 * connection cannot be found.
119 * @throws IOException If some other kind of I/O error occurs.
120 * @see "javax.microedition.io.Connector.openInputStream(String name)"
121 */
122 public InputStream openInputStream(String name) throws IOException;
123
124 /**
125 * Create and open a <code>DataInputStream</code> object for the specified
126 * name.
127 *
128 * @param name The URI for the connection.
129 * @return A <code>DataInputStream</code> object.
130 * @throws IllegalArgumentException If a parameter is invalid.
131 * @throws javax.microedition.io.ConnectionNotFoundException If the
132 * connection cannot be found.
133 * @throws IOException If some other kind of I/O error occurs.
134 * @see "javax.microedition.io.Connector.openDataInputStream(String name)"
135 */
136 public DataInputStream openDataInputStream(String name) throws IOException;
137
138 /**
139 * Create and open an <code>OutputStream</code> object for the specified name.
140 *
141 * @param name The URI for the connection.
142 * @return An <code>OutputStream</code> object.
143 * @throws IllegalArgumentException If a parameter is invalid.
144 * @throws javax.microedition.io.ConnectionNotFoundException If the
145 * connection cannot be found.
146 * @throws IOException If some other kind of I/O error occurs.
147 * @see "javax.microedition.io.Connector.openOutputStream(String name)"
148 */
149 public OutputStream openOutputStream(String name) throws IOException;
150
151 /**
152 * Create and open a <code>DataOutputStream</code> object for the specified
153 * name.
154 *
155 * @param name The URI for the connection.
156 * @return A <code>DataOutputStream</code> object.
157 * @throws IllegalArgumentException If a parameter is invalid.
158 * @throws javax.microedition.io.ConnectionNotFoundException If the
159 * connection cannot be found.
160 * @throws IOException If some other kind of I/O error occurs.
161 * @see "javax.microedition.io.Connector.openDataOutputStream(String name)"
162 */
163 public DataOutputStream openDataOutputStream(String name)
164 throws IOException;
165 }