com.uwyn.rife.cmf.dam
Class OrdinalManager

java.lang.Object
  extended by 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


Copyright © 2001-2007 Uwyn sprl/bvba. All Rights Reserved.