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
050public class FingerClient extends SocketClient {
051    /**
052     * The default FINGER port. Set to 79 according to RFC 1288.
053     */
054    public static final int DEFAULT_PORT = 79;
055
056    private static final String LONG_FLAG = "/W ";
057
058    private final transient char[] buffer = new char[1024];
059
060    /**
061     * The default FingerClient constructor. Initializes the default port to <code>DEFAULT_PORT</code>.
062     */
063    public FingerClient() {
064        setDefaultPort(DEFAULT_PORT);
065    }
066
067    /**
068     * Fingers the connected host and returns the input stream from the network connection of the finger query. This is equivalent to calling
069     * getInputStream(longOutput, ""). You must first connect to a finger server before calling this method, and you should disconnect after finishing reading
070     * the stream.
071     *
072     * @param longOutput Set to true if long output is requested, false if not.
073     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
074     * @throws IOException If an I/O error during the operation.
075     */
076    public InputStream getInputStream(final boolean longOutput) throws IOException {
077        return getInputStream(longOutput, "");
078    }
079
080    /**
081     * 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
082     * this method, and you should disconnect after finishing reading the stream.
083     *
084     * @param longOutput Set to true if long output is requested, false if not.
085     * @param user   The name of the user to finger.
086     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
087     * @throws IOException If an I/O error during the operation.
088     */
089    public InputStream getInputStream(final boolean longOutput, final String user) throws IOException {
090        return getInputStream(longOutput, user, null);
091    }
092
093    /**
094     * 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
095     * this method, and you should disconnect after finishing reading the stream.
096     *
097     * @param longOutput Set to true if long output is requested, false if not.
098     * @param user   The name of the user to finger.
099     * @param encoding   the character encoding that should be used for the query, null for the platform's default encoding
100     * @return The InputStream of the network connection of the finger query. Can be read to obtain finger results.
101     * @throws IOException If an I/O error during the operation.
102     */
103    public InputStream getInputStream(final boolean longOutput, final String user, final String encoding) throws IOException {
104        final DataOutputStream output;
105        final StringBuilder buffer = new StringBuilder(64);
106        if (longOutput) {
107            buffer.append(LONG_FLAG);
108        }
109        buffer.append(user);
110        buffer.append(SocketClient.NETASCII_EOL);
111
112        // Note: Charsets.toCharset() returns the platform default for null input
113        final byte[] encodedQuery = buffer.toString().getBytes(Charsets.toCharset(encoding).name()); // Java 1.6 can use
114                                                                                                     // charset directly
115
116        output = new DataOutputStream(new BufferedOutputStream(checkOpenOutputStream(), 1024));
117        output.write(encodedQuery, 0, encodedQuery.length);
118        output.flush();
119
120        return _input_;
121    }
122
123    /**
124     * 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
125     * disconnect afterward. This is equivalent to calling <code>query(longOutput, "")</code>.
126     *
127     * @param longOutput Set to true if long output is requested, false if not.
128     * @return The result of the finger query.
129     * @throws IOException If an I/O error occurs while reading the socket.
130     */
131    public String query(final boolean longOutput) throws IOException {
132        return query(longOutput, "");
133    }
134
135    /**
136     * 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
137     * should disconnect afterward.
138     *
139     * @param longOutput Set to true if long output is requested, false if not.
140     * @param user   The name of the user to finger.
141     * @return The result of the finger query.
142     * @throws IOException If an I/O error occurs while reading the socket.
143     */
144    public String query(final boolean longOutput, final String user) throws IOException {
145        int read;
146        final StringBuilder result = new StringBuilder(buffer.length);
147
148        try (final BufferedReader input = new BufferedReader(new InputStreamReader(getInputStream(longOutput, user), getCharset()))) {
149            while (true) {
150                read = input.read(buffer, 0, buffer.length);
151                if (read <= 0) {
152                    break;
153                }
154                result.append(buffer, 0, read);
155            }
156        }
157
158        return result.toString();
159    }
160
161}