edu.sdsc.inca
Class Client

java.lang.Object
  extended by edu.sdsc.inca.Component
      extended by edu.sdsc.inca.Client
Direct Known Subclasses:
AgentClient, DepotClient, ManagerClient

public class Client
extends Component

This class implements the functionality common to all Inca client classes. Along with defining an API that understands the Server protocol, it defines a main method that allows access to a Server via a telnet-style interface.


Field Summary
static java.lang.String CLIENT_OPTS
           
protected static org.apache.log4j.Logger logger
           
protected  ProtocolReader reader
           
protected  java.net.Socket socket
           
protected  ProtocolWriter writer
           
 
Fields inherited from class edu.sdsc.inca.Component
authenticate, cert, certPath, COMPONENT_OPTS, hostname, key, keyPath, logFile, password, port, trusted, trustedPath
 
Constructor Summary
Client()
           
 
Method Summary
 void close()
          Close the client socket to the server.
 java.lang.String commandGetLog()
          Retrieve the text in the server's log file, if any.
 void commandLogConfig(java.lang.String data)
          Send a log config message to the server.
 void commandPermit(java.lang.String dn, java.lang.String action)
          Send a permit command to the server.
 java.lang.String commandPing(java.lang.String data)
          Send a ping to the server and return the response data.
 void connect()
          Establish a connection to the server.
protected  java.lang.String dialog(java.lang.String command, java.lang.String data)
          Sends a statement to the server and returns the data from a successful response.
 java.lang.String getDn(boolean peer)
          Returns the DN associated with this connection.
 boolean isConnected()
          Query whether the client is presently connected.
static void main(java.lang.String[] args)
          A simple main method for exercising the Client.
 Statement read()
          Read the next statement from the server.
 void setConfiguration(java.util.Properties config)
          A convenience function for setting multiple configuration properties at once.
 void setServer(java.lang.String server, int defaultPort)
          Sets the host and port of the server to contact.
static void telnetDialog(Client c, java.lang.String prompt)
          Allows the user to use a client via a telnet-style interface.
 void write(Statement statement)
          Write a statement to the server.
 
Methods inherited from class edu.sdsc.inca.Component
addTrustedCert, configComponent, createSocket, getAuthenticate, getCertificate, getCertificatePath, getDn, getHostname, getKey, getKeyPath, getLogFile, getPassword, getPort, getTrustedCertificates, getTrustedPath, getUri, openResourceStream, readCredentials, readVersion, setAuthenticate, setCertificatePath, setHostname, setKeyPath, setLogFile, setPassword, setPort, setTrustedPath
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CLIENT_OPTS

public static final java.lang.String CLIENT_OPTS

logger

protected static org.apache.log4j.Logger logger

socket

protected java.net.Socket socket

reader

protected ProtocolReader reader

writer

protected ProtocolWriter writer
Constructor Detail

Client

public Client()
Method Detail

close

public void close()
Close the client socket to the server. If not called explicitly, this method will be called when the Client instance is destroyed.


commandGetLog

public java.lang.String commandGetLog()
                               throws java.io.IOException,
                                      ProtocolException
Retrieve the text in the server's log file, if any.

Returns:
the contents of the server's log, an empty string if none
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

commandLogConfig

public void commandLogConfig(java.lang.String data)
                      throws java.io.IOException,
                             ProtocolException
Send a log config message to the server.

Parameters:
data - a log4j setting of the form property=value
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

commandPing

public java.lang.String commandPing(java.lang.String data)
                             throws java.io.IOException,
                                    ProtocolException
Send a ping to the server and return the response data.

Parameters:
data - the ping message data
Returns:
the ping response data
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

commandPermit

public void commandPermit(java.lang.String dn,
                          java.lang.String action)
                   throws java.io.IOException,
                          ProtocolException
Send a permit command to the server.

Parameters:
dn - the DN of the entity allowed to perform an action
action - the action the entity is allowed to perform
Throws:
java.io.IOException - on read/write error
ProtocolException - on an invalid message

connect

public void connect()
             throws ConfigurationException,
                    java.io.IOException
Establish a connection to the server.

Throws:
ConfigurationException - if the configuration settings are invalid
java.io.IOException - if the attempt to contact the server fails

getDn

public java.lang.String getDn(boolean peer)
Returns the DN associated with this connection.

Parameters:
peer - indicates whether the local or peer DN is desired
Returns:
the desired DN; null if this connection is not secure

isConnected

public boolean isConnected()
Query whether the client is presently connected.

Returns:
true iff connected

read

public Statement read()
               throws java.io.IOException,
                      ProtocolException
Read the next statement from the server.

Returns:
the next statement
Throws:
java.io.IOException - on read error
ProtocolException - on an invalid message

setConfiguration

public void setConfiguration(java.util.Properties config)
                      throws ConfigurationException
A convenience function for setting multiple configuration properties at once. In addition to the keys recognized by the superclass, recognizes: "server", the specification of the server.

Overrides:
setConfiguration in class Component
Parameters:
config - contains client configuration values
Throws:
ConfigurationException - on a faulty configuration property value

setServer

public void setServer(java.lang.String server,
                      int defaultPort)
Sets the host and port of the server to contact.

Parameters:
server - contact spec of the form [protocol://]host[:port]
defaultPort - port to contact if server contains none

write

public void write(Statement statement)
           throws java.io.IOException
Write a statement to the server.

Parameters:
statement - the statement to write
Throws:
java.io.IOException - on write failure

dialog

protected java.lang.String dialog(java.lang.String command,
                                  java.lang.String data)
                           throws java.io.IOException,
                                  ProtocolException
Sends a statement to the server and returns the data from a successful response.

Parameters:
command - the command to send
data - the data to accompany the command
Returns:
the data from a non-error response
Throws:
java.io.IOException - on read failure
ProtocolException - if a failure message is received

telnetDialog

public static void telnetDialog(Client c,
                                java.lang.String prompt)
Allows the user to use a client via a telnet-style interface. Allows the contents of files to be substituted in commands via '< path' and output of commands to be redirected via '> path'.

Parameters:
c - the client to use
prompt - the user prompt

main

public static void main(java.lang.String[] args)
A simple main method for exercising the Client.
 usage: java inca.Client
-a|--auth boolean Authenticated (secure) connection? -c|--cert path Path to the authentication certificate -f|--file path Inca installation configuration file path -h|--help null Print help/usage -i|--init path Path to properties file -k|--key path Path to the authentication key -P|--password str Specify how to obtain encryption password -S|--server str Server specification; host:port -t|--trusted path Path to authentication trusted certificate dir -V|--version null Display program version

Each of these properties, other than --init, can also be specified in the initialization file or in system properties defined via the -D switch. In each of these cases, the configuration name must be prefixed with "inca.client.", e.g., use "inca.client.cert" to specify the cert value. Command line arguments override any properties specified in this fashion. If --file is specified, the main method reads the specified file and sends it to the Server in a setConfig message; otherwise, main allows the user to communicate with the Server via a telnet-style interface. Supported values for the --password argument are: "no" or "false" (no encryption); "yes", "true", or "stdin:prompt" (read password from stdin after optionally prompting); "pass:text" (specify the password directly--should only be used for testing and, possibly, in the init file).

Parameters:
args - command line arguments, as above.