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   *
51   ***/
52  
53  public class FingerClient extends SocketClient
54  {
55      /***
56       * The default FINGER port.  Set to 79 according to RFC 1288.
57       ***/
58      public static final int DEFAULT_PORT = 79;
59  
60      private static final String __LONG_FLAG = "/W ";
61  
62      private transient char[] __buffer = new char[1024];
63  
64      /***
65       * The default FingerClient constructor.  Initializes the
66       * default port to <code> DEFAULT_PORT </code>.
67       ***/
68      public FingerClient()
69      {
70          setDefaultPort(DEFAULT_PORT);
71      }
72  
73  
74      /***
75       * Fingers a user at the connected host and returns the output
76       * as a String.  You must first connect to a finger server before
77       * calling this method, and you should disconnect afterward.
78       *
79       * @param longOutput Set to true if long output is requested, false if not.
80       * @param username  The name of the user to finger.
81       * @return The result of the finger query.
82       * @exception IOException If an I/O error occurs while reading the socket.
83       ***/
84      public String query(boolean longOutput, String username) throws IOException
85      {
86          int read;
87          StringBuilder result = new StringBuilder(__buffer.length);
88          BufferedReader input;
89  
90          input =
91              new BufferedReader(new InputStreamReader(getInputStream(longOutput,
92                                 username), getCharset()));
93  
94          try {
95              while (true)
96              {
97                  read = input.read(__buffer, 0, __buffer.length);
98                  if (read <= 0) {
99                      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      *
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      *
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      *
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         // Note: Charsets.toCharset() returns the platform default for null input
171         byte[] encodedQuery = buffer.toString().getBytes(Charsets.toCharset(encoding).name()); // Java 1.6 can use charset directly
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      *
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 }