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}