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 */
017package org.apache.commons.net.finger;
018
019import java.io.BufferedOutputStream;
020import java.io.BufferedReader;
021import java.io.DataOutputStream;
022import java.io.IOException;
023import java.io.InputStream;
024import java.io.InputStreamReader;
025
026import org.apache.commons.net.SocketClient;
027import org.apache.commons.net.util.Charsets;
028
029/**
030 * The FingerClient class implements the client side of the Internet Finger Protocol defined in RFC 1288. To finger a host you create a FingerClient instance,
031 * connect to the host, query the host, and finally disconnect from the host. If the finger service you want to query is on a non-standard port, connect to the
032 * host at that port. Here's a sample use:
033 *
034 * <pre>
035 * FingerClient finger;
036 *
037 * finger = new FingerClient();
038 *
039 * try {
040 *     finger.connect("foo.bar.com");
041 *     System.out.println(finger.query("foobar", false));
042 *     finger.disconnect();
043 * } catch (IOException e) {
044 *     System.err.println("Error I/O exception: " + e.getMessage());
045 *     return;
046 * }
047 * </pre>
048 *
049 */
050
051public class FingerClient extends SocketClient {
052    /**
053     * The default FINGER port. Set to 79 according to RFC 1288.
054     */
055    public static final int DEFAULT_PORT = 79;
056
057    private static final String LONG_FLAG = "/W ";
058
059    private final transient char[] buffer = new char[1024];
060
061    /**
062     * The default FingerClient constructor. Initializes the default port to <code> DEFAULT_PORT </code>.
063     */
064    public FingerClient() {
065        setDefaultPort(DEFAULT_PORT);
066    }
067
068    /**
069     * Fingers the connected host and returns the input stream from the network connection of the finger query. This is equivalent to calling
070     * getInputStream(longOutput, ""). You must first connect to a finger server before calling this method, and you should disconnect after finishing reading
071     * the stream.
072     *
073     * @param longOutput Set to true if long output is requested, false if not.
074     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
075     * @throws IOException If an I/O error during the operation.
076     */
077    public InputStream getInputStream(final boolean longOutput) throws IOException {
078        return getInputStream(longOutput, "");
079    }
080
081    /**
082     * Fingers a user and returns the input stream from the network connection of the finger query. You must first connect to a finger server before calling
083     * this method, and you should disconnect after finishing reading the stream.
084     *
085     * @param longOutput Set to true if long output is requested, false if not.
086     * @param username   The name of the user to finger.
087     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
088     * @throws IOException If an I/O error during the operation.
089     */
090    public InputStream getInputStream(final boolean longOutput, final String username) throws IOException {
091        return getInputStream(longOutput, username, null);
092    }
093
094    /**
095     * Fingers a user and returns the input stream from the network connection of the finger query. You must first connect to a finger server before calling
096     * this method, and you should disconnect after finishing reading the stream.
097     *
098     * @param longOutput Set to true if long output is requested, false if not.
099     * @param username   The name of the user to finger.
100     * @param encoding   the character encoding that should be used for the query, null for the platform's default encoding
101     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
102     * @throws IOException If an I/O error during the operation.
103     */
104    public InputStream getInputStream(final boolean longOutput, final String username, final String encoding) throws IOException {
105        final DataOutputStream output;
106        final StringBuilder buffer = new StringBuilder(64);
107        if (longOutput) {
108            buffer.append(LONG_FLAG);
109        }
110        buffer.append(username);
111        buffer.append(SocketClient.NETASCII_EOL);
112
113        // Note: Charsets.toCharset() returns the platform default for null input
114        final byte[] encodedQuery = buffer.toString().getBytes(Charsets.toCharset(encoding).name()); // Java 1.6 can use
115                                                                                                     // charset directly
116
117        output = new DataOutputStream(new BufferedOutputStream(_output_, 1024));
118        output.write(encodedQuery, 0, encodedQuery.length);
119        output.flush();
120
121        return _input_;
122    }
123
124    /**
125     * Fingers the connected host and returns the output as a String. You must first connect to a finger server before calling this method, and you should
126     * disconnect afterward. This is equivalent to calling <code> query(longOutput, "") </code>.
127     *
128     * @param longOutput Set to true if long output is requested, false if not.
129     * @return The result of the finger query.
130     * @throws IOException If an I/O error occurs while reading the socket.
131     */
132    public String query(final boolean longOutput) throws IOException {
133        return query(longOutput, "");
134    }
135
136    /**
137     * Fingers a user at the connected host and returns the output as a String. You must first connect to a finger server before calling this method, and you
138     * should disconnect afterward.
139     *
140     * @param longOutput Set to true if long output is requested, false if not.
141     * @param username   The name of the user to finger.
142     * @return The result of the finger query.
143     * @throws IOException If an I/O error occurs while reading the socket.
144     */
145    public String query(final boolean longOutput, final String username) throws IOException {
146        int read;
147        final StringBuilder result = new StringBuilder(buffer.length);
148
149        try (final BufferedReader input = new BufferedReader(new InputStreamReader(getInputStream(longOutput, username), getCharset()))) {
150            while (true) {
151                read = input.read(buffer, 0, buffer.length);
152                if (read <= 0) {
153                    break;
154                }
155                result.append(buffer, 0, read);
156            }
157        }
158
159        return result.toString();
160    }
161
162}