Package rife.cmf.dam

Class OrdinalManager

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

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    OrdinalManager.Direction
     

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final OrdinalManager.Direction
    DOWN
     
    static final OrdinalManager.Direction
    UP
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    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

    Modifier and Type
    Method
    Description
    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 Details

  • Constructor Details

    • 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 Details

    • 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

      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:

    • 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

      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:

    • 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

      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:

    • 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:

    • 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:

    • 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

      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:

    • 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

      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:

    • 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

      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:

    • 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

      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:

    • 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