com.uwyn.rife.cmf.dam
Class OrdinalManager

java.lang.Object
  com.uwyn.rife.cmf.dam.OrdinalManager

All Implemented Interfaces:

Cloneable

public class OrdinalManager
extends Object
implements Cloneable

This class makes it possible to easily manage an integer ordinal column that is typically used to determine the order of the rows in a specific table.

The basic version manages the ordinals for the entire table, but it's also possible to create an OrdinalManager that uses several independent ranges of ordinals according to a restricting integer column.

For example, consider the following 'article' table:

id          INT
categoryId  INT
ordinal     INT
name        VARCHAR(30)

with the following rows:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       0 | some article
  0 |          1 |       1 | another one
  3 |          1 |       2 | boom boom
  1 |          2 |       0 | this is yet an article
  5 |          2 |       1 | an article for you
  4 |          3 |       0 | our latest article
  6 |          3 |       1 | important one

You can clearly see three independent ordinal ranges according to the categoryId column.

The OrdinalManager allows you to easily change the order of the articles by moving them up and down with the provided methods: move, up and down. It's also possible to do more complex manipulations by using the lower level methods: free, update, tighten and obtainInsertOrdinal.

Since:

1.0

Version:

$Revision: 3634 $

Author:

Geert Bevin (gbevin[remove] at uwyn dot com)

Nested Class Summary

static class

OrdinalManager.Direction

Field Summary

static OrdinalManager.Direction	DOWN Has to be used to indicate an downwards direction for the move method.
static OrdinalManager.Direction	UP Has to be used to indicate an upwards direction for the move method.

Constructor Summary

OrdinalManager(Datasource datasource, String table, String ordinalColumn)
Creates a new OrdinalManager that manages ordinals globally for the specified table.

OrdinalManager(Datasource datasource, String table, String ordinalColumn, String restrictColumn)
Creates a new OrdinalManager that manages ordinals for the specified table in independent ranges according to a restricting integer column.

Method Summary

Object	clone() Simply clones the instance with the default clone method.
boolean	down(int ordinal) Moves a row with a specific ordinal downwards within the entire table.
boolean	down(long restrictId, int ordinal) Moves a row with a specific ordinal downwards within the range restricted by the provided ID.
boolean	free(int ordinal) Frees up a slot for the specified ordinal within the entire table., this is done by incrementing everything after it by 1 to make space.
boolean	free(long restrictId, int ordinal) Frees up a slot for the specified ordinal within the range restricted by the provided ID, this is done by incrementing everything after it by 1 to make space.
String	getOrdinalColumn() Retrieves the name of the ordinal column.
String	getRestrictColumn() Retrieves the name of the restricting column.
String	getTable() Retrieves the name of the table of this OrdinalManager.
boolean	move(int fromOrdinal, int toOrdinal) Moves a row with a specific ordinal to the location of another ordinal within the entire table.
boolean	move(long restrictId, int fromOrdinal, int toOrdinal) Moves a row with a specific ordinal to the location of another ordinal within the range restricted by the provided ID.
boolean	move(OrdinalManager.Direction direction, int ordinal) Moves the position of a row with a specific ordinal within the entire table.
boolean	move(OrdinalManager.Direction direction, long restrictId, int ordinal) Moves the position of a row with a specific ordinal within the range restricted by the provided ID.
int	obtainInsertOrdinal() Returns the next freely available ordinal that can be used to insert a new row behind all the other rows in the entire table.
int	obtainInsertOrdinal(long restrictId) Returns the next freely available ordinal that can be used to insert a new row behind all the other rows in the range restricted by the provided ID.
boolean	tighten() Tightens the series of ordinal within the entire table so that no spaces are present in between the ordinals.
boolean	tighten(long restrictId) Tightens the series of ordinal within the range restricted by the provided ID so that no spaces are present in between the ordinals.
boolean	up(int ordinal) Moves a row with a specific ordinal upwards within the entire table.
boolean	up(long restrictId, int ordinal) Moves a row with a specific ordinal upwards within the range restricted by the provided ID.
boolean	update(int currentOrdinal, int newOrdinal) Changes the ordinal of a certain row to a new value.
boolean	update(long restrictId, int currentOrdinal, int newOrdinal) Changes the ordinal of a certain row with a specific restriction ID to a new value.

Methods inherited from class java.lang.Object

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

Field Detail

UP

public static final OrdinalManager.Direction UP

Has to be used to indicate an upwards direction for the move method.

DOWN

public static final OrdinalManager.Direction DOWN

Has to be used to indicate an downwards direction for the move method.

Constructor Detail

OrdinalManager

public OrdinalManager(Datasource datasource,
                      String table,
                      String ordinalColumn)

Creates a new OrdinalManager that manages ordinals globally for the specified table.

Parameters:

datasource - the datasource where the table is accessible

table - the name of the table that will be managed

ordinalColumn - the name of the column that contains the integer ordinals

Since:

1.0

OrdinalManager

public OrdinalManager(Datasource datasource,
                      String table,
                      String ordinalColumn,
                      String restrictColumn)

Creates a new OrdinalManager that manages ordinals for the specified table in independent ranges according to a restricting integer column.

Parameters:

datasource - the datasource where the table is accessible

table - the name of the table that will be managed

ordinalColumn - the name of the column that contains the integer ordinals

restrictColumn - the name of the column whose values will partition the ordinals in independent ranges

Since:

1.0

Method Detail

getTable

public String getTable()

Retrieves the name of the table of this OrdinalManager.

Returns:

the name of the table

Since:

1.0

getOrdinalColumn

public String getOrdinalColumn()

Retrieves the name of the ordinal column.

Returns:

the name of the ordinal column

Since:

1.0

getRestrictColumn

public String getRestrictColumn()

Retrieves the name of the restricting column.

Returns:

the name of the restricting column; or

null if this OrdinalManager manages the table globally

Since:

1.0

move

public boolean move(OrdinalManager.Direction direction,
                    int ordinal)

Moves the position of a row with a specific ordinal within the entire table.

Parameters:

direction - the direction in which to move: OrdinalManager.UP or OrdinalManager.DOWN

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

move(Direction, long, int)

move

public boolean move(OrdinalManager.Direction direction,
                    long restrictId,
                    int ordinal)

Moves the position of a row with a specific ordinal within the range restricted by the provided ID.

Parameters:

direction - the direction in which to move: OrdinalManager.UP or OrdinalManager.DOWN

restrictId - the restriction ID value

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

move(Direction, int)

up

public boolean up(int ordinal)

Moves a row with a specific ordinal upwards within the entire table.

Parameters:

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

up(long, int)

up

public boolean up(long restrictId,
                  int ordinal)

Moves a row with a specific ordinal upwards within the range restricted by the provided ID.

Parameters:

restrictId - the restriction ID value

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

up(int)

down

public boolean down(int ordinal)

Moves a row with a specific ordinal downwards within the entire table.

Parameters:

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

down(long, int)

down

public boolean down(long restrictId,
                    int ordinal)

Moves a row with a specific ordinal downwards within the range restricted by the provided ID.

Parameters:

restrictId - the restriction ID value

ordinal - the ordinal of the row that has to be moved

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

down(int)

move

public boolean move(int fromOrdinal,
                    int toOrdinal)

Moves a row with a specific ordinal to the location of another ordinal within the entire table.

Parameters:

fromOrdinal - the ordinal of the row that has to be moved

toOrdinal - the ordinal of the row where the from row has will be put above

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

down(int)

move

public boolean move(long restrictId,
                    int fromOrdinal,
                    int toOrdinal)

Moves a row with a specific ordinal to the location of another ordinal within the range restricted by the provided ID.

Parameters:

restrictId - the restriction ID value

fromOrdinal - the ordinal of the row that has to be moved

toOrdinal - the ordinal of the row where the from row has will be put above

Returns:

true if the move was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

down(int)

free

public boolean free(int ordinal)

Frees up a slot for the specified ordinal within the entire table., this is done by incrementing everything after it by 1 to make space.

So for example issuing the method free(1) on the following table:

 id | ordinal | name
----+---------+-----------------------
  2 |       0 | some article
  0 |       1 | another one
  1 |       2 | this is yet an article

will result in:

 id | ordinal | name
----+---------+-----------------------
  2 |       0 | some article
  0 |       2 | another one
  1 |       3 | this is yet an article

Parameters:

ordinal - an integer representing the ordinal to free

Returns:

true if the slot was freed up correctly; or

false if the operation wasn't possible

Since:

1.0

See Also:

free(long, int)

free

public boolean free(long restrictId,
                    int ordinal)

Frees up a slot for the specified ordinal within the range restricted by the provided ID, this is done by incrementing everything after it by 1 to make space.

So for example issuing the method free(2, 0) on the following table:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       0 | some article
  0 |          1 |       1 | another one
  3 |          1 |       2 | boom boom
  1 |          2 |       0 | this is yet an article
  5 |          2 |       1 | an article for you
  4 |          3 |       0 | our latest article
  6 |          3 |       1 | important one

will result into:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       0 | some article
  0 |          1 |       1 | another one
  3 |          1 |       2 | boom boom
  1 |          2 |       1 | this is yet an article
  5 |          2 |       2 | an article for you
  4 |          3 |       0 | our latest article
  6 |          3 |       1 | important one

Parameters:

restrictId - the id by which to restrict with

ordinal - an int representation the ordinal to free

Returns:

true if the slot was freed up correctly; or

false if the operation wasn't possible

Since:

1.0

See Also:

free(int)

update

public boolean update(int currentOrdinal,
                      int newOrdinal)

Changes the ordinal of a certain row to a new value.

This simply updates the value of the ordinal column and doesn't execute any other logic.

Parameters:

currentOrdinal - the ordinal of the row that has to be updated

newOrdinal - the new ordinal value

Returns:

true if the update was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

update(long, int, int)

update

public boolean update(long restrictId,
                      int currentOrdinal,
                      int newOrdinal)

Changes the ordinal of a certain row with a specific restriction ID to a new value.

This simply updates the value of the ordinal column and doesn't execute any other logic.

Parameters:

restrictId - the id by which to restrict with

currentOrdinal - the ordinal of the row that has to be updated

newOrdinal - the new ordinal value

Returns:

true if the update was executed successfully; or

false if this wasn't the case

Since:

1.0

See Also:

update(int, int)

tighten

public boolean tighten()

Tightens the series of ordinal within the entire table so that no spaces are present in between the ordinals.

So for example issuing the method tighten() on the following table:

 id | ordinal | name
----+---------+-----------------------
  2 |       0 | some article
  0 |       2 | another one
  1 |       5 | this is yet an article

will result in:

 id | ordinal | name
----+---------+-----------------------
  2 |       0 | some article
  0 |       1 | another one
  1 |       2 | this is yet an article

Returns:

true if the tightening was executed correctly; or

false if the operation wasn't possible

Since:

1.0

See Also:

tighten(long)

tighten

public boolean tighten(long restrictId)

Tightens the series of ordinal within the range restricted by the provided ID so that no spaces are present in between the ordinals.

So for example issuing the method tighten(2) on the following table:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       1 | some article
  0 |          1 |       2 | another one
  3 |          1 |       7 | boom boom
  1 |          2 |       4 | this is yet an article
  5 |          2 |       8 | an article for you
  4 |          3 |       4 | our latest article
  6 |          3 |       5 | important one

will result in:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       1 | some article
  0 |          1 |       2 | another one
  3 |          1 |       7 | boom boom
  1 |          2 |       0 | this is yet an article
  5 |          2 |       1 | an article for you
  4 |          3 |       4 | our latest article
  6 |          3 |       5 | important one

Parameters:

restrictId - the id by which to restrict with

Returns:

true if the tightening was executed correctly; or

false if the operation wasn't possible

Since:

1.0

See Also:

tighten()

obtainInsertOrdinal

public int obtainInsertOrdinal()

Returns the next freely available ordinal that can be used to insert a new row behind all the other rows in the entire table.

So for example issuing the method obtainInsertOrdinal() on the following table:

 id | ordinal | name
----+---------+-----------------------
  2 |       0 | some article
  0 |       1 | another one
  1 |       2 | this is yet an article

Will return the value 3.

Returns:

the requested ordinal; or

0 if no ordinals are present within the table yet

Since:

1.0

See Also:

obtainInsertOrdinal(long)

obtainInsertOrdinal

public int obtainInsertOrdinal(long restrictId)

Returns the next freely available ordinal that can be used to insert a new row behind all the other rows in the range restricted by the provided ID.

So for example issuing the method obtainInsertOrdinal(3) on the following table:

 id | categoryId | ordinal | name
----+------------+---------+-----------------------
  2 |          1 |       0 | some article
  0 |          1 |       1 | another one
  3 |          1 |       2 | boom boom
  1 |          2 |       0 | this is yet an article
  5 |          2 |       1 | an article for you
  4 |          3 |       0 | our latest article
  6 |          3 |       1 | important one

Will return the value 2.

Parameters:

restrictId - the id by which to restrict with

Returns:

the requested ordinal; or

0 if no ordinals are present within the range yet

Since:

1.0

See Also:

obtainInsertOrdinal()

clone

public Object clone()

Simply clones the instance with the default clone method. This creates a shallow copy of all fields and the clone will in fact just be another reference to the same underlying data. The independence of each cloned instance is consciously not respected since they rely on resources that can't be cloned.

Overrides:

clone in class Object

Since:

1.0