The leJOS Tutorial

| Start of Tutorial > Start of Trail

Trail: Essential leJOS classes
Lesson: Utilities

# Utilities: Recycling

Other than on the PC with its constantly enlarging sizes of RAM, Memory is precious on small devices like the RCX.
Since there is no mechanism on Java to free memory at a determined point of time, and particularly with the lack of a garbage collector with leJOS, allocating objects on the heap is liable to set forth some kind of "out of memory" behavior of your robot. In peculiar, memory consuming collections like arrays are prone to make itself a nuisance.

To help this, some new `josx.util` package located classes have been introduced in leJOS' version 2.1.0 with the task of providing a recycling mechanism:

- `Recyclable` an interface for an recyclable object
- `AbstractRecycable` an abstract base class for Recyclables which implements some of `Recyclable` methods
- `RecyclableArray` a recyclable array implementing the `Recyclable` interface
- `Recycler` an abstract base class which is able to recycle Recyclables
- `ArrayRecycler` an array recycler

The idea is simple but effective: instead of creating every new instance of your object with its constructor using `new()`, you order such a new instance by a `Recycler`, which may be thought as a factory that stores currently unused objects and delivers them on order.
All the user has to do is

1. to implement the `Recyclable` interface for the classes he wants to be recycled that way,
2. to order such objects from the recycler by calling `Recycler.allocate()`,
3. to hand them out back to the recycler when they are no longer needed (by calling `Recycler.recycle([recyclable object])) and`
4. to extend the abstract `Recycler` class in overwriting its `createInstance()` method (don't worry: as a rule that requires no more than creating a new instance of your recyclable class using `new`).

## Declaring instances of a class to be recycable

For the instances of a class to be recycable, the class should extend the abstract `josx.util.AbstractRecyclable` class; this means, it has to implement the following two methods:

- `public void init()` called, when an instance is allocated by the recycler
- `public void release()` called by the user when the instance is no longer needed; you should release any resources here, including nested Recyclables.

Of course you are free to implement the `Recyclable` directly; in this case you have to implement also the `getNextRecyclable()` and `setNextRecyclable()` by yourself.

## Building a Recycler

To recycle recyclable instances, you need a recycler which manages the process of allocating and releasing the memory for these instances. This is most easily done by extending the abstract `josx.util.Recycler` class, which means that your recycler has to to implement the

                public Recyclable createInstance()

method and adapt it to create an instance of your particular recyclable class.

Of course you can build your own recycler, which means that you have to take care of the complete recycling process by yourself.

## Recycling array entries

For recycable arrays there exists the `josx.util.RecyclableArray` class already, which delivers all the basic functionalities you would expect from an array like get(), put() and getLength().
The associated recycler is `josx.util.ArrayRecycler` which extends `josx.util.Recycler` and implements its abstract methods - ready to be used.

## Two complete examples that use the Recycling classes

are ObjectRecyclingSample.java and ArrayRecyclingSample.java which may be found in the `examples/test/recycling` section of the leJOS tree.

## The Recycling API

may be found here.

The leJOS Tutorial

| Start of Tutorial > Start of Trail