001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.net.finger;
018
019 import java.io.BufferedReader;
020 import java.io.IOException;
021 import java.io.InputStream;
022 import java.io.InputStreamReader;
023 import java.io.BufferedOutputStream;
024 import java.io.DataOutputStream;
025
026 import org.apache.commons.net.SocketClient;
027
028 /***
029 * The FingerClient class implements the client side of the Internet Finger
030 * Protocol defined in RFC 1288. To finger a host you create a
031 * FingerClient instance, connect to the host, query the host, and finally
032 * disconnect from the host. If the finger service you want to query is on
033 * a non-standard port, connect to the host at that port.
034 * Here's a sample use:
035 * <pre>
036 * FingerClient finger;
037 *
038 * finger = new FingerClient();
039 *
040 * try {
041 * finger.connect("foo.bar.com");
042 * System.out.println(finger.query("foobar", false));
043 * finger.disconnect();
044 * } catch(IOException e) {
045 * System.err.println("Error I/O exception: " + e.getMessage());
046 * return;
047 * }
048 * </pre>
049 * <p>
050 * <p>
051 ***/
052
053 public class FingerClient extends SocketClient
054 {
055 /***
056 * The default FINGER port. Set to 79 according to RFC 1288.
057 ***/
058 public static final int DEFAULT_PORT = 79;
059
060 private static final String __LONG_FLAG = "/W ";
061
062 private transient char[] __buffer = new char[1024];
063
064 /***
065 * The default FingerClient constructor. Initializes the
066 * default port to <code> DEFAULT_PORT </code>.
067 ***/
068 public FingerClient()
069 {
070 setDefaultPort(DEFAULT_PORT);
071 }
072
073
074 /***
075 * Fingers a user at the connected host and returns the output
076 * as a String. You must first connect to a finger server before
077 * calling this method, and you should disconnect afterward.
078 * <p>
079 * @param longOutput Set to true if long output is requested, false if not.
080 * @param username The name of the user to finger.
081 * @return The result of the finger query.
082 * @exception IOException If an I/O error occurs while reading the socket.
083 ***/
084 public String query(boolean longOutput, String username) throws IOException
085 {
086 int read;
087 StringBuilder result = new StringBuilder(__buffer.length);
088 BufferedReader input;
089
090 input =
091 new BufferedReader(new InputStreamReader(getInputStream(longOutput,
092 username)));
093
094 try {
095 while (true)
096 {
097 read = input.read(__buffer, 0, __buffer.length);
098 if (read <= 0) {
099 break;
100 }
101 result.append(__buffer, 0, read);
102 }
103 } finally {
104 input.close();
105 }
106
107 return result.toString();
108 }
109
110
111 /***
112 * Fingers the connected host and returns the output
113 * as a String. You must first connect to a finger server before
114 * calling this method, and you should disconnect afterward.
115 * This is equivalent to calling <code> query(longOutput, "") </code>.
116 * <p>
117 * @param longOutput Set to true if long output is requested, false if not.
118 * @return The result of the finger query.
119 * @exception IOException If an I/O error occurs while reading the socket.
120 ***/
121 public String query(boolean longOutput) throws IOException
122 {
123 return query(longOutput, "");
124 }
125
126
127 /***
128 * Fingers a user and returns the input stream from the network connection
129 * of the finger query. You must first connect to a finger server before
130 * calling this method, and you should disconnect after finishing reading
131 * the stream.
132 * <p>
133 * @param longOutput Set to true if long output is requested, false if not.
134 * @param username The name of the user to finger.
135 * @return The InputStream of the network connection of the finger query.
136 * Can be read to obtain finger results.
137 * @exception IOException If an I/O error during the operation.
138 ***/
139 public InputStream getInputStream(boolean longOutput, String username)
140 throws IOException
141 {
142 return getInputStream(longOutput, username, null);
143 }
144
145 /***
146 * Fingers a user and returns the input stream from the network connection
147 * of the finger query. You must first connect to a finger server before
148 * calling this method, and you should disconnect after finishing reading
149 * the stream.
150 * <p>
151 * @param longOutput Set to true if long output is requested, false if not.
152 * @param username The name of the user to finger.
153 * @param encoding the character encoding that should be used for the query,
154 * null for the platform's default encoding
155 * @return The InputStream of the network connection of the finger query.
156 * Can be read to obtain finger results.
157 * @exception IOException If an I/O error during the operation.
158 ***/
159 public InputStream getInputStream(boolean longOutput, String username, String encoding)
160 throws IOException
161 {
162 DataOutputStream output;
163 StringBuilder buffer = new StringBuilder(64);
164 if (longOutput) {
165 buffer.append(__LONG_FLAG);
166 }
167 buffer.append(username);
168 buffer.append(SocketClient.NETASCII_EOL);
169
170 byte[] encodedQuery =
171 (encoding == null ? buffer.toString().getBytes() : buffer.toString().getBytes(encoding));
172
173 output = new DataOutputStream(new BufferedOutputStream(_output_, 1024));
174 output.write(encodedQuery, 0, encodedQuery.length);
175 output.flush();
176
177 return _input_;
178 }
179
180
181 /***
182 * Fingers the connected host and returns the input stream from
183 * the network connection of the finger query. This is equivalent to
184 * calling getInputStream(longOutput, ""). You must first connect to a
185 * finger server before calling this method, and you should disconnect
186 * after finishing reading the stream.
187 * <p>
188 * @param longOutput Set to true if long output is requested, false if not.
189 * @return The InputStream of the network connection of the finger query.
190 * Can be read to obtain finger results.
191 * @exception IOException If an I/O error during the operation.
192 ***/
193 public InputStream getInputStream(boolean longOutput) throws IOException
194 {
195 return getInputStream(longOutput, "");
196 }
197
198 }