com.lts.ipc.sharedmemory
Class SharedMemory

java.lang.Object
  com.lts.ipc.sharedmemory.SharedMemory

public class SharedMemory
extends java.lang.Object

A shared memory segment.

Description

This class wraps the MappedByteBuffer class to make it a little easier to use.

#quickstart

Instances of this class must correspond to a file on the host system that is read/write to the running process.

Quickstart

• Create or connect to an existing segment via SharedMemory(String, int).
• Read from the segment via #read(byte[], int, int, int).
• Write to the segment via write(byte[], int, int, int).
• You do not need to explicitly close your connection.

Author:

cnh

See Also:

MappedByteBuffer

Field Summary

protected java.nio.MappedByteBuffer	byteBuffer
protected java.nio.channels.FileChannel	channel
protected boolean	connected
protected java.io.File	segmentFile
protected int	size

Constructor Summary

SharedMemory()

SharedMemory(java.io.File file, int size)

SharedMemory(java.lang.String fileName, int size)

Method Summary

void	connect(java.io.File file, int size) Connect this segment to the underlying shared memory segment.
void	connect(java.lang.String fileName, int size)
byte	getByte(int offset) Return the byte at a particular location in the segment.
java.nio.MappedByteBuffer	getByteBuffer()
java.lang.String	getLine(int offset, byte[] buffer) Retrieve a line of text from the segment.
java.lang.String	getLine(int offset, int maxBytes) Return a string from the specified location in the segment; the string may only take the specified number of bytes.
java.io.File	getSegmentFile()
int	getSize()
boolean	isConnected()
boolean	isFileCreator()
void	lock() Reserve the shared memory segment.
void	put(int offset, byte[] data) Put some data at a location.
void	putLine(int offset, java.lang.String s)
void	putString(int offset, java.lang.String s)
int	read(byte[] buf) Read bytes from the start of the segment.
int	read(byte[] buf, int bufferOffset) Read bytes from the segment into a buffer, storing them in a location offset from the start of the buffer.
int	read(int segmentOffset, byte[] buf) Read in data from the segment, starting at a particular location in the segment.
int	read(int soffset, byte[] buf, int boffset, int length) Read bytes up to a specified number of bytes into the provided buffer.
void	setByteBuffer(java.nio.MappedByteBuffer byteBuffer)
void	setFileCreator(boolean fileCreator)
void	unlock()
void	write(byte[] buf)
void	write(byte[] buf, int segmentOffset)
void	write(byte[] buf, int buffOffset, int bufLength, int segmentOffset) Write an array of bytes into a specified location in the segment, starting with a particular byte in the buffer and continuing for a specified number of bytes.
void	write(byte value, int offset)
void	write(int value, int offset)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

segmentFile

protected java.io.File segmentFile

byteBuffer

protected java.nio.MappedByteBuffer byteBuffer

size

protected int size

connected

protected boolean connected

channel

protected java.nio.channels.FileChannel channel

Constructor Detail

SharedMemory

public SharedMemory()

SharedMemory

public SharedMemory(java.io.File file,
                    int size)
             throws IPCException

Throws:

IPCException

SharedMemory

public SharedMemory(java.lang.String fileName,
                    int size)
             throws IPCException

Throws:

IPCException

Method Detail

isFileCreator

public boolean isFileCreator()

setFileCreator

public void setFileCreator(boolean fileCreator)

getByteBuffer

public java.nio.MappedByteBuffer getByteBuffer()

setByteBuffer

public void setByteBuffer(java.nio.MappedByteBuffer byteBuffer)

isConnected

public boolean isConnected()

getSegmentFile

public java.io.File getSegmentFile()

getSize

public int getSize()

connect

public void connect(java.io.File file,
                    int size)
             throws IPCException

Connect this segment to the underlying shared memory segment.

Parameters:

name - The name of the file for the segment.

size - The size of the segment.

Throws:

IPCException

connect

public void connect(java.lang.String fileName,
                    int size)
             throws IPCException

Throws:

IPCException

write

public void write(byte[] buf,
                  int buffOffset,
                  int bufLength,
                  int segmentOffset)
           throws IPCException

Write an array of bytes into a specified location in the segment, starting with a particular byte in the buffer and continuing for a specified number of bytes.

Parameters:

buf - The data to write.

buffOffset - The location, relative to the start of the buffer, where the data should be obtained.

bufLength - The number of bytes to write.

segmentOffset - The location in the buffer where the data should be written.

Throws:

IPCException - The method will throw this exception if the segment is not actually connected to the underlying shared memory block.

write

public void write(byte value,
                  int offset)

write

public void write(byte[] buf)
           throws IPCException

Throws:

IPCException

write

public void write(int value,
                  int offset)

write

public void write(byte[] buf,
                  int segmentOffset)
           throws IPCException

Throws:

IPCException

read

public int read(int soffset,
                byte[] buf,
                int boffset,
                int length)
         throws IPCException

Read bytes up to a specified number of bytes into the provided buffer.

This method returns the number of bytes that were actually read. If fewer bytes are left in the segment than requested, then the method returns the number of bytes read.

Parameters:

buf - The buffer where the bytes read should be stored.

boffset - The offset into buf where the bytes should be placed.

length - The number of bytes to try to read.

soffset - The offset within the segment where the read should start.

Returns:

The number of bytes actually read. See description for details.

Throws:

IPCException - This method throws this exception with the error set to IPCException.Errors.NotConnected if the instance has not been connected to a segment yet.

read

public int read(byte[] buf,
                int bufferOffset)
         throws IPCException

Read bytes from the segment into a buffer, storing them in a location offset from the start of the buffer.

This method is equivalent to calling:

     read(0, buf, bufferOffset, buf.length);
 

Parameters:

buf - The buffer where the bytes read should be placed.

bufferOffset - The location in the buffer where the bytes read should start.

Returns:

The number of bytes actually read.

Throws:

IPCException - read(int, byte[], int, int).

See Also:

read(int, byte[], int, int)

read

public int read(byte[] buf)
         throws IPCException

Read bytes from the start of the segment.

This method is equivalent to calling

     read(0, buf, 0, buf.length);
 

See that method for details.

Parameters:

buf - The buffer where bytes read should be placed.

Returns:

The number of bytes read.

Throws:

IPCException - see read(int, byte[], int, int).

See Also:

#read(int, byte[], int, int)}

read

public int read(int segmentOffset,
                byte[] buf)
         throws IPCException

Read in data from the segment, starting at a particular location in the segment.

This method is equivalent to calling

     read(segmentOffset, buf, 0, buf.length);
 

See that method for details.

Parameters:

segmentOffset - The byte index into the segment where reading should start.

buf - Where the bytes read should be placed.

Returns:

The number of bytes actually read.

Throws:

IPCException - see read(int, byte[], int, int)

See Also:

read(int, byte[], int, int)

getByte

public byte getByte(int offset)
             throws IPCException

Return the byte at a particular location in the segment.

Parameters:

offset - The location of the byte in the segment.

Returns:

The value of the byte.

Throws:

java.lang.IndexOutOfBoundsException - If offset is negative or larger than the size of the segment minus 1.

IPCException

lock

public void lock()
          throws java.io.IOException

Reserve the shared memory segment.

It is not clear from the JRE documentation whether or not locking the segment will stop modifications to the segment or not. for details.

Throws:

java.io.IOException

unlock

public void unlock()
            throws java.io.IOException

Throws:

java.io.IOException

put

public void put(int offset,
                byte[] data)
         throws IPCException

Put some data at a location.

The entire contents of the buffer are written to a position in the segment defined by the offset parameter. If the amount of data exceeds the size of the segment, the method throws an exception.

Parameters:

offset - The location in the segment, in bytes, where the data will be written.

data - The data to write. The contents of the array will be written.

Throws:

IPCException

getLine

public java.lang.String getLine(int offset,
                                byte[] buffer)
                         throws java.io.IOException,
                                IPCException

Retrieve a line of text from the segment.

This method goes to the specified location in the segment and tries to read in characters. It continues until it hits the end of the segment, or it encounters the end of the string. The end of a string is denoted by any of the following sequences of characters:

• '\n'
• '\r'
• '\n\r'

The method uses the underlying character set as defined by Charset.defaultCharset()

The supplied buffer is used to determine the maximum length of the string in that, if no line termination has been encountered before a number of bytes equal to the size of the buffer are read, then the characters accumulated so far are returned.

Any line termination character(s) are not included in the string returned.

Parameters:

offset - The location in the segment to start reading.

buffer - A buffer to contain the bytes from the shared memory segment.

Returns:

The resulting string.

Throws:

java.io.IOException - If the method tries to read past the end of the segment, either because it started outside the segment or because the string did not have any line termination.

IPCException - This exception is thrown if the object is not currently connected to a shared memory segment.

getLine

public java.lang.String getLine(int offset,
                                int maxBytes)
                         throws java.io.IOException,
                                IPCException

Return a string from the specified location in the segment; the string may only take the specified number of bytes.

This method is equivalent to calling

     byte[] buf = new byte[maxBytes];
     getLine(offset, buf);
 

See that method for details.

If the underlying string does not end after maxBytes, the method returns the substring that takes up that number of bytes.

Parameters:

offset - The location within the segment where the string starts.

maxBytes - The maximum number of bytes for the string.

Returns:

The string found.

Throws:

java.io.IOException - See getLine(int, byte[]).

IPCException - See getLine(int, byte[]).

See Also:

getLine(int, byte[])

putString

public void putString(int offset,
                      java.lang.String s)

putLine

public void putLine(int offset,
                    java.lang.String s)