com.lts.ipc.fifo
Class FIFO

java.lang.Object
  extended by com.lts.ipc.fifo.FIFO

public class FIFO
extends java.lang.Object

A one-way interprocess communications channel.

NOTE

Because of the way that Windows implements named pipes, one process must call the create() method before the named pipe can be used. This is in addition to whether that process will be exclusively reading from or writing to the pipe.

On Linux, a named pipe (FIFO) will persist after the process that created it terminates, allowing subsequent clients to use it without taking on a client or role.

Unfortunately, using this information will introduce a platform dependency in the system.

Quickstart

Creator/Writer Process

 byte[] buffer;
 String name;
 // create an instance for buffer and fill it with data
 // set name to a valid file name 
 ... 
 NamedPipe pipe = new NamedPipe(name);
 pipe.create();
 pipe.openWriter();
 pipe.write(buffer);
 

Reader Process

 byte[] buffer;
 String name;
 // create an instance for buffer
 // set name to the same name as the writer is using
 ...
 NamedPipe pipe = new NamedPipe(name);
 pipe.openReader();
 int count = pipe.read(buffer);
 // process the data received
 ...
 

Description

Please see the note on client/server roles before using this class

This class provides a named pipe IPC primitive. These are sometimes referred to as FIFOs or message queues.

In this context a named pipe provides a one-way, synchronous communications channel between two processes. Note that this class only allows one-way communications even if the underlying mechanism the operating system supports is two-way.

The class uses file naming as explained in the package description. In the case of this class, the file name will refer to an operating system file. On Linux, this will be the name of the FIFO that is a file in the file system that implements the pipe. On windows, this will be a file that contains the actual name of the pipe.

Before using an instance of the class, the openReader() or openWriter() method should be used to establish the role it will be taking when communicating. Attempting to use an instance without properly initializing may result in unpredictable behavior.

Once the role has been established the read(byte[]), read(byte[], int, int), write(byte[]) and write(byte[], int, int) methods, as appropriate, can be used to send or receive information.

Virtual File Name

This class uses virtual and actual files to implement the underlying primitive. On platforms such as Linux, the virtual and actual file names are the same and both refer to a special file on the system that represents the communications channel.

In the case of Windows, named pipes must use a special file name of the form: \\.\pipe\<name>. Such file names cannot be used on Linux.

In order to provide a reasonably platform independent solution, the Windows implementation of named pipes uses two file names for the pipe: a virtual name name and an actual name.

The virtual name is basically any valid file name on the system. The file identified in the virtual name corresponds to an actual file in the system, which contains the actual name of the named pipe.

The actual name is then used to identify the named pipe to Windows.

Author:
cnh

Nested Class Summary
static class FIFO.BlockingMode
           
 
Field Summary
static int DEFAULT_BUFFER_SIZE
           
 
Constructor Summary
FIFO(java.lang.String virtualName)
          Create a named pipe with the specified virtual name.
FIFO(java.lang.String virtualName, int timeoutMsec)
           
 
Method Summary
 void create()
           
protected  java.lang.String getActualName()
           
 FIFO.BlockingMode getBlockingMode()
           
protected  FIFOImpl.PipeDirection getDirection()
           
protected  FIFOImpl getImpl()
           
 java.io.InputStream getInputStream()
           
 java.io.InputStream getInputStream(int timeoutMsec)
           
 java.io.OutputStream getOutputStream()
           
 int getTimeoutMsec()
           
 java.lang.String getVirtualName()
           
protected  void initialize(java.lang.String virtualName)
           
 void open(FIFOImpl.PipeDirection direction)
          Open the named pipe, taking on the role of reader or writer.
 void openReader()
          Connect to the named pipe, taking on the role of reader.
 void openWriter()
          Connect to the named pipe, taking on the role of writer.
 int read(byte[] buffer)
          Read from the named pipe, blocking until data becomes available.
 int read(byte[] buffer, int offset, int length)
          Read some data from the named pipe, blocking if the data is not available.
protected  java.lang.String readActualName(java.lang.String virtualName)
           
 void selectForWriting(int timeoutMsec)
           
 void setBlockingMode(FIFO.BlockingMode blockingMode)
           
protected  void setDirection(FIFOImpl.PipeDirection direction)
           
protected  void setImpl(FIFOImpl impl)
           
 void setTimeoutMsec(int timeout)
           
 int write(byte[] buffer)
          Write some data to the named pipe.
 int write(byte[] buffer, int offset, int length)
          Write some data to the named pipe.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_BUFFER_SIZE

public static final int DEFAULT_BUFFER_SIZE
See Also:
Constant Field Values
Constructor Detail

FIFO

public FIFO(java.lang.String virtualName)
Create a named pipe with the specified virtual name.

Parameters:
virtualName - The file to be used for the named pipe. See the class description for details about how and why the virtual file name is used.

FIFO

public FIFO(java.lang.String virtualName,
            int timeoutMsec)
Method Detail

getBlockingMode

public FIFO.BlockingMode getBlockingMode()

setBlockingMode

public void setBlockingMode(FIFO.BlockingMode blockingMode)

getTimeoutMsec

public int getTimeoutMsec()

setTimeoutMsec

public void setTimeoutMsec(int timeout)

getImpl

protected FIFOImpl getImpl()

setImpl

protected void setImpl(FIFOImpl impl)

initialize

protected void initialize(java.lang.String virtualName)

create

public void create()
            throws IPCException
Throws:
IPCException

readActualName

protected java.lang.String readActualName(java.lang.String virtualName)
                                   throws IPCException
Throws:
IPCException

open

public void open(FIFOImpl.PipeDirection direction)
          throws IPCException
Open the named pipe, taking on the role of reader or writer.

On Linux, users of named pipes need to either read or write to a named pipe, they should not do both. Therefore this method establishes how the client is going to use the pipe and then connects to it.

Parameters:
direction - The role the client wants to take on: reader or writer.
Throws:
IPCException - If a problem is encountered while trying to connect to the pipe.

openWriter

public void openWriter()
                throws IPCException
Connect to the named pipe, taking on the role of writer.

This method is equivalent to calling #open(PipeDirection) with an argument of FIFOImpl.PipeDirection.Writer.

Throws:
IPCException - If a problem is encountered while trying to connect to the pipe.
See Also:
#open(PipeDirection)

openReader

public void openReader()
                throws IPCException
Connect to the named pipe, taking on the role of reader.

This method is equivalent to calling #open(PipeDirection) with an argument of FIFOImpl.PipeDirection.Reader.

Throws:
IPCException - If a problem is encountered while trying to connect to the pipe.
See Also:
#open(PipeDirection)

getDirection

protected FIFOImpl.PipeDirection getDirection()

setDirection

protected void setDirection(FIFOImpl.PipeDirection direction)

getActualName

protected java.lang.String getActualName()

read

public int read(byte[] buffer)
         throws IPCException
Read from the named pipe, blocking until data becomes available.

This method is equivalent to calling read(buffer, 0, buff.length). See that class for additional details.

Parameters:
buffer - The buffer where the data read from the pipe should be placed.
Returns:
The number of bytes actually read.
Throws:
IPCException - If a problem is encountered while reading from the named pipe.
See Also:
read(byte[], int, int)

read

public int read(byte[] buffer,
                int offset,
                int length)
         throws IPCException
Read some data from the named pipe, blocking if the data is not available.

This method will block if data is not available when it is called. The method may read less than the specified amount of data.

It is an error on some platforms to read from a pipe that has been opened for writing.

Parameters:
buffer - The buffer where the data read should be placed.
offset - Where the data should start in the buffer.
length - The size of the buffer, in bytes.
Returns:
The number of bytes read.
Throws:
IPCException - If a problem is encountered while trying to read from the pipe.

write

public int write(byte[] buffer)
          throws IPCException
Write some data to the named pipe.

This method is equivalent to calling write(buffer, 0, buffer.length). Please see that method for additional details.

Parameters:
buffer - The buffer that contains the data.
Returns:
The number of bytes actually written.
Throws:
IPCException - If a problem is encountered while writing the data.

write

public int write(byte[] buffer,
                 int offset,
                 int length)
          throws IPCException
Write some data to the named pipe.

This method writes data to the named pipe and will block if the pipe is currently full.

It is an error to write to a named pipe that the client opened as a reader.

The method may perform a partial write, in which case only some of the data in the buffer was actually written. In that case, the return value will be less than the length parameter.

Parameters:
buffer - The buffer that contains the data to write.
offset - Where in the buffer that the data starts.
length - The number of bytes of data to write.
Returns:
The number of bytes of data that were actually written.
Throws:
IPCException - If a problem is encountered while trying to write the data.

getInputStream

public java.io.InputStream getInputStream(int timeoutMsec)
                                   throws java.io.IOException
Throws:
java.io.IOException

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException
Throws:
java.io.IOException

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException
Throws:
java.io.IOException

getVirtualName

public java.lang.String getVirtualName()

selectForWriting

public void selectForWriting(int timeoutMsec)