josx.platform.rcx
Class PersistentMemoryArea

java.lang.Object
  josx.platform.rcx.PersistentMemoryArea

public class PersistentMemoryArea

extends Object

A memory area for persistent storage. The memory persists between runs of a program. Downloading a new program will trash the area (unless you're very lucky).

The magic number should be different for each application (use a random integer).

At the moment there can be only one PersistentMemoryArea, that will be reinitialized if you change the magic number. This may change in the future, with more than one area and magic number used to distinguish them.

In case you experience problems, the specific restrictions are as follows (which might help you fix the problem):

1. There can be only one persistent area of memory.
2. It will not survive an application reload unless it is exactly the same application (which means the application is axactly the same size, it uses the same magic number and the persistent area is exactly the same size).
3. You can call PersistentMemoryArea.get(magic, size) exactly once in any one run of an application. If you call it more than once you will get an out-of-memory error.
4. There is a very remote chance that on the first run of an application it will be falsely determined that the persistent area already exists. For this to happen, the area of heap used will have to contain an exact match for the magic number and size requested.

Method Summary

static PersistentMemoryArea	get(int magic, int size) Allocate a persistent array of 'size' bytes.
byte	readByte(int i) Read the byte at index 'i'
void	writeByte(int i, byte b) Write a byte at index 'i'

Methods inherited from class java.lang.Object

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

Method Detail

get

public static PersistentMemoryArea get(int magic,
                                       int size)
                                throws OutOfMemoryError

Allocate a persistent array of 'size' bytes. If this is a new array, the values are initialized to zero.

Parameters:

magic - a 2 byte integer used to idenitfy the specific memory area.

size - the size in bytes. This should be in the range 0 thru 511.

Throws:

OutOfMemoryError - not enoug memory to allocate the array.

readByte

public byte readByte(int i)
              throws ArrayIndexOutOfBoundsException

Read the byte at index 'i'

Parameters:

i - the index starting at 0.

Throws:

ArrayIndexOutOfBoundsException - if the index is out of bounds.

writeByte

public void writeByte(int i,
                      byte b)
               throws ArrayIndexOutOfBoundsException

Write a byte at index 'i'

Parameters:

i - the index starting at 0.

b - the byte value.

Throws:

ArrayIndexOutOfBoundsException - if the index is out of bounds.