View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    *
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   *
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  package org.apache.commons.net.finger;
18  
19  import java.io.BufferedReader;
20  import java.io.IOException;
21  import java.io.InputStream;
22  import java.io.InputStreamReader;
23  import java.io.BufferedOutputStream;
24  import java.io.DataOutputStream;
25  
26  import org.apache.commons.net.SocketClient;
27  import org.apache.commons.net.util.Charsets;
28  
29  /***
30   * The FingerClient class implements the client side of the Internet Finger
31   * Protocol defined in RFC 1288.  To finger a host you create a
32   * FingerClient instance, connect to the host, query the host, and finally
33   * disconnect from the host.  If the finger service you want to query is on
34   * a non-standard port, connect to the host at that port.
35   * Here's a sample use:
36   * <pre>
37   *    FingerClient finger;
38   *
39   *    finger = new FingerClient();
40   *
41   *    try {
42   *      finger.connect("foo.bar.com");
43   *      System.out.println(finger.query("foobar", false));
44   *      finger.disconnect();
45   *    } catch(IOException e) {
46   *      System.err.println("Error I/O exception: " + e.getMessage());
47   *      return;
48   *    }
49   * </pre>
50   * <p>
51   * <p>
52   ***/
53  
54  public class FingerClient extends SocketClient
55  {
56      /***
57       * The default FINGER port.  Set to 79 according to RFC 1288.
58       ***/
59      public static final int DEFAULT_PORT = 79;
60  
61      private static final String __LONG_FLAG = "/W ";
62  
63      private transient char[] __buffer = new char[1024];
64  
65      /***
66       * The default FingerClient constructor.  Initializes the
67       * default port to <code> DEFAULT_PORT </code>.
68       ***/
69      public FingerClient()
70      {
71          setDefaultPort(DEFAULT_PORT);
72      }
73  
74  
75      /***
76       * Fingers a user at the connected host and returns the output
77       * as a String.  You must first connect to a finger server before
78       * calling this method, and you should disconnect afterward.
79       * <p>
80       * @param longOutput Set to true if long output is requested, false if not.
81       * @param username  The name of the user to finger.
82       * @return The result of the finger query.
83       * @exception IOException If an I/O error occurs while reading the socket.
84       ***/
85      public String query(boolean longOutput, String username) throws IOException
86      {
87          int read;
88          StringBuilder result = new StringBuilder(__buffer.length);
89          BufferedReader input;
90  
91          input =
92              new BufferedReader(new InputStreamReader(getInputStream(longOutput,
93                                 username), getCharsetName())); // Java 1.6 can use getCharset()
94  
95          try {
96              while (true)
97              {
98                  read = input.read(__buffer, 0, __buffer.length);
99                  if (read <= 0) {
100                     break;
101                 }
102                 result.append(__buffer, 0, read);
103             }
104         } finally {
105             input.close();
106         }
107 
108         return result.toString();
109     }
110 
111 
112     /***
113      * Fingers the connected host and returns the output
114      * as a String.  You must first connect to a finger server before
115      * calling this method, and you should disconnect afterward.
116      * This is equivalent to calling <code> query(longOutput, "") </code>.
117      * <p>
118      * @param longOutput Set to true if long output is requested, false if not.
119      * @return The result of the finger query.
120      * @exception IOException If an I/O error occurs while reading the socket.
121      ***/
122     public String query(boolean longOutput) throws IOException
123     {
124         return query(longOutput, "");
125     }
126 
127 
128     /***
129      * Fingers a user and returns the input stream from the network connection
130      * of the finger query.  You must first connect to a finger server before
131      * calling this method, and you should disconnect after finishing reading
132      * the stream.
133      * <p>
134      * @param longOutput Set to true if long output is requested, false if not.
135      * @param username  The name of the user to finger.
136      * @return The InputStream of the network connection of the finger query.
137      *         Can be read to obtain finger results.
138      * @exception IOException If an I/O error during the operation.
139      ***/
140     public InputStream getInputStream(boolean longOutput, String username)
141     throws IOException
142     {
143         return getInputStream(longOutput, username, null);
144     }
145 
146     /***
147      * Fingers a user and returns the input stream from the network connection
148      * of the finger query.  You must first connect to a finger server before
149      * calling this method, and you should disconnect after finishing reading
150      * the stream.
151      * <p>
152      * @param longOutput Set to true if long output is requested, false if not.
153      * @param username  The name of the user to finger.
154      * @param encoding the character encoding that should be used for the query,
155      *        null for the platform's default encoding
156      * @return The InputStream of the network connection of the finger query.
157      *         Can be read to obtain finger results.
158      * @exception IOException If an I/O error during the operation.
159      ***/
160     public InputStream getInputStream(boolean longOutput, String username, String encoding)
161     throws IOException
162     {
163         DataOutputStream output;
164         StringBuilder buffer = new StringBuilder(64);
165         if (longOutput) {
166             buffer.append(__LONG_FLAG);
167         }
168         buffer.append(username);
169         buffer.append(SocketClient.NETASCII_EOL);
170 
171         // Note: Charsets.toCharset() returns the platform default for null input
172         byte[] encodedQuery = buffer.toString().getBytes(Charsets.toCharset(encoding).name()); // Java 1.6 can use charset directly
173 
174         output = new DataOutputStream(new BufferedOutputStream(_output_, 1024));
175         output.write(encodedQuery, 0, encodedQuery.length);
176         output.flush();
177 
178         return _input_;
179     }
180 
181 
182     /***
183      * Fingers the connected host and returns the input stream from
184      * the network connection of the finger query.  This is equivalent to
185      * calling getInputStream(longOutput, "").  You must first connect to a
186      * finger server before calling this method, and you should disconnect
187      * after finishing reading the stream.
188      * <p>
189      * @param longOutput Set to true if long output is requested, false if not.
190      * @return The InputStream of the network connection of the finger query.
191      *         Can be read to obtain finger results.
192      * @exception IOException If an I/O error during the operation.
193      ***/
194     public InputStream getInputStream(boolean longOutput) throws IOException
195     {
196         return getInputStream(longOutput, "");
197     }
198 
199 }