qflib 0.98.0

de.qfs.lib.logrmi
Class RemoteLogWriter

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--de.qfs.lib.logrmi.LogClientImplBase
                          |
                          +--de.qfs.lib.logrmi.RemoteLogWriter
All Implemented Interfaces:
LogClient, LogWriter, java.rmi.Remote, java.io.Serializable

public class RemoteLogWriter
extends LogClientImplBase
implements LogWriter

The RemoteLogWriter class takes care of all the necessary details to connect to a LogServer and pass the log messages created by a program to it. The convenience methods logRemote and stopLogging handle all the details.

There are two possible modes of operation: Contact a server as soon as the RemoteLogWriter is created or register with the RMI registry to get contacted later by a LogServer. The most useful mode of operation is to combine these two, since then the user doesn't need to concern himself with the order in which server and clients are started.

If the RemoteLogWriter is to register itself with the RMI registry, a few additional things have to be decided:
- Which registry port to use
- Whether to create a registry, if the rmiregistry tool hasn't been started. This can be useful when a long-running server program is using its own registry port anyway, but should be used with care, as the termination of the program that created the registry will destroy all other registrations.
- Whether LogServers from different machines are allowed to connect. This can be very useful but is also a great security hole. The decision depends on your kind of program and whether your machine is safe behind a firewall.

To handle the log messages, the RemoteLogWriter must either be set as the default writer with Log.setLogWriter, or added to the filter chain with the help of a LevelFilter and Log.addFilter.

Since:
0.98.0
Version:
$Revision: 1.5 $
Author:
Gregor Schmid
See Also:
Serialized Form

Fields inherited from class java.rmi.server.RemoteObject
ref
 
Fields inherited from interface de.qfs.lib.logrmi.LogClient
REGISTRY_BASE_NAME
 
Constructor Summary
RemoteLogWriter(java.lang.String name)
          Create a new RemoteLogWriter and connect to a LogServer.
 
Method Summary
 void close()
          Close the LogWriter and disconnect from the server.
 void connect(LogServer logServer)
          Tell the LogClient that it should disengage from the registry and connect itself to a LogServer.
 void connect(java.lang.String server)
          Connect to a LogServer.
 void disconnect()
          Disconnect from the LogServer.
 LogFormat getFormat()
          Get the format the LogWriter uses to format LogEntries.
static LevelFilter logRemote(java.lang.String name, int port, boolean createRegistry, boolean localOnly)
          Create a new RemoteLogWriter, register it with the RMI registry and use a LevelFilter to put it into the Log filter chain.
static LevelFilter logRemote(java.lang.String server, java.lang.String name)
          Create a new RemoteLogWriter, connect it to a LogServer and use a LevelFilter to put it into the Log filter chain.
static LevelFilter logRemote(java.lang.String server, java.lang.String name, int port, boolean createRegistry, boolean localOnly)
          Create a new RemoteLogWriter and connect it to a LogServer and register it with the RMI registry.
 void register(int port, boolean createRegistry, boolean localOnly)
          Register the RemoteLogWriter with the RMI registry.
 void setFormat(LogFormat format)
          Set the format the LogWriter should use to format LogEntries.
static void stopLogging()
          Remove the RemoteLogWriter instance from the Log filter chain, disconnect from the LogServer and remove the instance from the RMI registry.
 void write(LogEntry logEntry)
          Take a LogEntry and pass it to the LogServer.
 void write(LogEntry[] entries)
          Send all messages from the list to the remote listener.
 
Methods inherited from class java.rmi.server.UnicastRemoteObject
clone, exportObject, exportObject, exportObject, unexportObject
 
Methods inherited from class java.rmi.server.RemoteServer
getClientHost, getLog, setLog
 
Methods inherited from class java.rmi.server.RemoteObject
equals, getRef, hashCode, toString, toStub
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Constructor Detail

RemoteLogWriter

public RemoteLogWriter(java.lang.String name)
                throws java.rmi.RemoteException
Create a new RemoteLogWriter and connect to a LogServer.
Parameters:
name - The name to connect under.
Throws:
java.rmi.RemoteException - If something RMI specific goes wrong.
Method Detail

logRemote

public static LevelFilter logRemote(java.lang.String server,
                                    java.lang.String name)
                             throws java.net.MalformedURLException,
                                    java.rmi.NotBoundException,
                                    java.rmi.RemoteException
Create a new RemoteLogWriter, connect it to a LogServer and use a LevelFilter to put it into the Log filter chain.
Parameters:
server - The servername to connect to in the format used by java.rmi.Naming.lookup.
name - The name to connect under.
Returns:
The new LevelFilter. Unless you change its level via LevelFilter.setLevel, it will log all messages via RMI. If you only call this method once in your application, you can use stopLogging to remove the filter and close the writer, otherwise you have to save this reference to the filter and clean up yourself.
Throws:
java.net.MalformedURLException - If the server URL is bad.
java.rmi.NotBoundException - If the server is not bound under that name.
java.rmi.RemoteException - If something RMI specific goes wrong.

logRemote

public static LevelFilter logRemote(java.lang.String name,
                                    int port,
                                    boolean createRegistry,
                                    boolean localOnly)
                             throws java.rmi.RemoteException
Create a new RemoteLogWriter, register it with the RMI registry and use a LevelFilter to put it into the Log filter chain.
Parameters:
name - The name to use when connecting to a LogServer.
port - The registry port to use. The value -1 means use the standard RMI registry port.
createRegistry - Whether to create a new Registry if none is available.
localOnly - If true, only LogServers from the same network address as the RemoteLogWriter are allowed to connect.
Returns:
The new LevelFilter. Unless you change its level via LevelFilter.setLevel, it will log all messages via RMI. If you only call this method once in your application, you can use stopLogging to remove the filter and close the writer, otherwise you have to save this reference to the filter and clean up yourself.
Throws:
java.rmi.RemoteException - If something RMI specific goes wrong.

logRemote

public static LevelFilter logRemote(java.lang.String server,
                                    java.lang.String name,
                                    int port,
                                    boolean createRegistry,
                                    boolean localOnly)
                             throws java.net.MalformedURLException,
                                    java.rmi.NotBoundException,
                                    java.rmi.RemoteException
Create a new RemoteLogWriter and connect it to a LogServer and register it with the RMI registry. If either of these succeeds, no Exception is thrown, even if the other method fails, and a LevelFilter is used to put the writer into the Log filter chain.
Parameters:
server - The servername to connect to in the format used by java.rmi.Naming.lookup.
name - The name to connect under.
port - The registry port to use. The value -1 means use the standard RMI registry port.
createRegistry - Whether to create a new Registry if none is available.
localOnly - If true, only LogServers from the same network address as the RemoteLogWriter are allowed to connect.
Returns:
The new LevelFilter. Unless you change its level via LevelFilter.setLevel, it will log all messages via RMI. If you only call this method once in your application, you can use stopLogging to remove the filter and close the writer, otherwise you have to save this reference to the filter and clean up yourself.
Throws:
java.net.MalformedURLException - If the server URL is bad.
java.rmi.NotBoundException - If the server is not bound under that name.
java.rmi.RemoteException - If something RMI specific goes wrong.

stopLogging

public static void stopLogging()
Remove the RemoteLogWriter instance from the Log filter chain, disconnect from the LogServer and remove the instance from the RMI registry.

connect

public void connect(java.lang.String server)
             throws java.net.MalformedURLException,
                    java.rmi.NotBoundException,
                    java.rmi.RemoteException
Connect to a LogServer.
Parameters:
server - The servername to connect to in the format used by java.rmi.Naming.lookup.
Throws:
java.net.MalformedURLException - If the server URL is bad.
java.rmi.NotBoundException - If the server is not bound under that name.
java.rmi.RemoteException - If something RMI specific goes wrong.

register

public void register(int port,
                     boolean createRegistry,
                     boolean localOnly)
              throws java.rmi.RemoteException
Register the RemoteLogWriter with the RMI registry.
Parameters:
port - The registry port to use, -1 for default.
createRegistry - Whether to create the registry if none exists.
localOnly - If true, only LogServers from the same network address as the RemoteLogWriter are allowed to connect.
Throws:
java.rmi.RemoteException - If no working Registry can be found or created.

disconnect

public void disconnect()
Disconnect from the LogServer.

write

public void write(LogEntry logEntry)
Take a LogEntry and pass it to the LogServer.
Specified by:
write in interface LogWriter
Parameters:
logEntry - The entry to pass on.
Returns:
True if the entry should be passed on to the next filter.

write

public void write(LogEntry[] entries)
Send all messages from the list to the remote listener.
Specified by:
write in interface LogWriter
Parameters:
entries - The list of LogEntries.

close

public void close()
Close the LogWriter and disconnect from the server.
Specified by:
close in interface LogWriter

setFormat

public void setFormat(LogFormat format)
Set the format the LogWriter should use to format LogEntries. Noop.
Specified by:
setFormat in interface LogWriter
Parameters:
format - The format to use.

getFormat

public LogFormat getFormat()
Get the format the LogWriter uses to format LogEntries.
Specified by:
getFormat in interface LogWriter
Returns:
Null.

connect

public void connect(LogServer logServer)
             throws java.rmi.RemoteException
Tell the LogClient that it should disengage from the registry and connect itself to a LogServer.
Overrides:
connect in class LogClientImplBase
Parameters:
logServer - The LogServer to connect to.
Throws:
java.rmi.RemoteException - If something RMI specific goes wrong.

qflib 0.98.0