KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > osgi > service > io > ConnectorService


1 /*
2  * $Header: /cvshome/build/org.osgi.service.io/src/org/osgi/service/io/ConnectorService.java,v 1.9 2006/07/12 21:22:12 hargrave Exp $
3  *
4  * Copyright (c) OSGi Alliance (2002, 2006). All Rights Reserved.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */
18 package org.osgi.service.io;
19
20 import java.io.*;
21
22 import javax.microedition.io.Connection;
23 import javax.microedition.io.Connector;
24
25 /**
26  * The Connector Service should be called to create and open
27  * <code>javax.microedition.io.Connection</code> objects.
28  *
29  * When an <code>open*</code> method is called, the implementation of the
30  * Connector Service will examine the specified name for a scheme. The Connector
31  * Service will then look for a Connection Factory service which is registered
32  * with the service property <code>IO_SCHEME</code> which matches the scheme. The
33  * <code>createConnection</code> method of the selected Connection Factory will
34  * then be called to create the actual <code>Connection</code> object.
35  *
36  * <p>
37  * If more than one Connection Factory service is registered for a particular
38  * scheme, the service with the highest ranking (as specified in its
39  * <code>service.ranking</code> property) is called. If there is a tie in ranking,
40  * the service with the lowest service ID (as specified in its
41  * <code>service.id</code> property), that is the service that was registered
42  * first, is called. This is the same algorithm used by
43  * <code>BundleContext.getServiceReference</code>.
44  *
45  * @version $Revision: 1.9 $
46  */
47 public interface ConnectorService {
48     /**
49      * Read access mode.
50      *
51      * @see "javax.microedition.io.Connector.READ"
52      */
53     public static final int READ = Connector.READ;
54     /**
55      * Write access mode.
56      *
57      * @see "javax.microedition.io.Connector.WRITE"
58      */
59     public static final int WRITE = Connector.WRITE;
60     /**
61      * Read/Write access mode.
62      *
63      * @see "javax.microedition.io.Connector.READ_WRITE"
64      */
65     public static final int READ_WRITE = Connector.READ_WRITE;
66
67     /**
68      * Create and open a <code>Connection</code> object for the specified name.
69      *
70      * @param name The URI for the connection.
71      * @return A new <code>javax.microedition.io.Connection</code> object.
72      * @throws IllegalArgumentException If a parameter is invalid.
73      * @throws javax.microedition.io.ConnectionNotFoundException If the
74      * connection cannot be found.
75      * @throws IOException If some other kind of I/O error occurs.
76      * @see "javax.microedition.io.Connector.open(String name)"
77      */
78     public Connection open(String JavaDoc name) throws IOException;
79
80     /**
81      * Create and open a <code>Connection</code> object for the specified name and
82      * access mode.
83      *
84      * @param name The URI for the connection.
85      * @param mode The access mode.
86      * @return A new <code>javax.microedition.io.Connection</code> object.
87      * @throws IllegalArgumentException If a parameter is invalid.
88      * @throws javax.microedition.io.ConnectionNotFoundException If the
89      * connection cannot be found.
90      * @throws IOException If some other kind of I/O error occurs.
91      * @see "javax.microedition.io.Connector.open(String name, int mode)"
92      */
93     public Connection open(String JavaDoc name, int mode) throws IOException;
94
95     /**
96      * Create and open a <code>Connection</code> object for the specified name,
97      * access mode and timeouts.
98      *
99      * @param name The URI for the connection.
100      * @param mode The access mode.
101      * @param timeouts A flag to indicate that the caller wants timeout
102      * exceptions.
103      * @return A new <code>javax.microedition.io.Connection</code> object.
104      * @throws IllegalArgumentException If a parameter is invalid.
105      * @throws javax.microedition.io.ConnectionNotFoundException If the
106      * connection cannot be found.
107      * @throws IOException If some other kind of I/O error occurs.
108      * @see "<code>javax.microedition.io.Connector.open</code>"
109      */
110     public Connection open(String JavaDoc name, int mode, boolean timeouts)
111             throws IOException;
112
113     /**
114      * Create and open an <code>InputStream</code> object for the specified name.
115      *
116      * @param name The URI for the connection.
117      * @return An <code>InputStream</code> object.
118      * @throws IllegalArgumentException If a parameter is invalid.
119      * @throws javax.microedition.io.ConnectionNotFoundException If the
120      * connection cannot be found.
121      * @throws IOException If some other kind of I/O error occurs.
122      * @see "javax.microedition.io.Connector.openInputStream(String name)"
123      */
124     public InputStream openInputStream(String JavaDoc name) throws IOException;
125
126     /**
127      * Create and open a <code>DataInputStream</code> object for the specified
128      * name.
129      *
130      * @param name The URI for the connection.
131      * @return A <code>DataInputStream</code> object.
132      * @throws IllegalArgumentException If a parameter is invalid.
133      * @throws javax.microedition.io.ConnectionNotFoundException If the
134      * connection cannot be found.
135      * @throws IOException If some other kind of I/O error occurs.
136      * @see "javax.microedition.io.Connector.openDataInputStream(String name)"
137      */
138     public DataInputStream openDataInputStream(String JavaDoc name) throws IOException;
139
140     /**
141      * Create and open an <code>OutputStream</code> object for the specified name.
142      *
143      * @param name The URI for the connection.
144      * @return An <code>OutputStream</code> object.
145      * @throws IllegalArgumentException If a parameter is invalid.
146      * @throws javax.microedition.io.ConnectionNotFoundException If the
147      * connection cannot be found.
148      * @throws IOException If some other kind of I/O error occurs.
149      * @see "javax.microedition.io.Connector.openOutputStream(String name)"
150      */
151     public OutputStream openOutputStream(String JavaDoc name) throws IOException;
152
153     /**
154      * Create and open a <code>DataOutputStream</code> object for the specified
155      * name.
156      *
157      * @param name The URI for the connection.
158      * @return A <code>DataOutputStream</code> object.
159      * @throws IllegalArgumentException If a parameter is invalid.
160      * @throws javax.microedition.io.ConnectionNotFoundException If the
161      * connection cannot be found.
162      * @throws IOException If some other kind of I/O error occurs.
163      * @see "javax.microedition.io.Connector.openDataOutputStream(String name)"
164      */
165     public DataOutputStream openDataOutputStream(String JavaDoc name)
166             throws IOException;
167 }
168
Popular Tags