net.sf.basedb.core
Class Unit

java.lang.Object
  net.sf.basedb.core.BasicItem<UnitData>
      net.sf.basedb.core.Unit

All Implemented Interfaces:

AccessControlled, Identifiable, Nameable, Removable

public class Unit
extends BasicItem<UnitData>
implements Nameable, Removable

This class is used to represent a specific unit that can be used with annotations. A unit must be related to the reference unit of the quantity. See Quantity.getReferenceUnit() for examples.

Version:

2.9

Author:

Nicklas

See Also:

Quantity, Essentials of the SI: Base & derived units

Last modified

$Date: 2010-11-22 09:02:13 +0100 (Mon, 22 Nov 2010) $

Field Summary

static int	MAX_SYMBOL_LENGTH The maximum length of the display symbol that can be stored in the database.
static Item	TYPE The type of item represented by this class.

Fields inherited from interface net.sf.basedb.core.Nameable

MAX_DESCRIPTION_LENGTH, MAX_NAME_LENGTH

Constructor Summary

Unit(UnitData data)
Creates a unit item.

Method Summary

void	addSymbol(String symbol) Add a symbol to this unit.
void	changeReferenceFactorAndOffset(double factor, double offset) Changes the factor and offset used for converting values in this unit into the reference unit.
(package private) UnitData	findOtherUnit(org.hibernate.Session session, String symbol) Find the unit with a given symbol that has the same quantity as this unit.
double	fromOther(double value, Unit other) Convert a value from another unit to this unit.
double	fromReferenceUnit(double value) Convert a value from the reference unit to this unit.
static Unit	getById(DbControl dc, int id) Get a Unit object when you know the ID.
String	getDescription() Get the description for the item.
String	getDisplaySymbol() Get the display symbol to use when displaying values with this unit.
<T> Formatter<T>	getFormatter(Formatter<T> parent) Create a formatter for formatting values with this unit.
String	getName() Get the name of the item.
static Unit	getNew(DbControl dc, Quantity quantity, String displaySymbol) Create a new Unit item.
Quantity	getQuantity() Get the quantity this unit belongs to.
static ItemQuery<Unit>	getQuery() Get a query configured to retrieve units.
double	getReferenceFactor() Get the factor that is used for converting values in this unit into the reference unit of the quantity.
double	getReferenceOffset() Get the offset that is used for converting values in this unit into the reference unit of the quantity.
Set<String>	getSymbols() Get all symbols that are registered for this unit.
Item	getType() Get the type of item represented by the object.
Set<ItemProxy>	getUsingItems() Get all: AnnotationType:s using this unit as default unit Annotation:s using this unit
boolean	isRemoved() Check if the removed flag is set for this item.
boolean	isUsed() Check if: Annotation types are using this unit as default unit Annotations are using this unit
(package private) void	onBeforeCommit(Transactional.Action action) Set property filters that use this unit to null when the unit is deleted.
void	removeSymbol(String symbol) Remove a symbol from this unit.
void	setDescription(String description) Set the description for the item.
void	setDisplaySymbol(String symbol) Set the display symbol for this unit.
void	setName(String name) Set the name of the item.
private void	setQuantity(Quantity quantity)
void	setRemoved(boolean removed) Set the removed flag for this item.
void	setSymbols(Set<String> symbols) Set the symbols that should be registered for this unit.
double	toReferenceUnit(double value) Convert a value from this unit to the reference unit.
double	toUnit(double value, Unit other) Convert a value from this unit to another unit.

Methods inherited from class net.sf.basedb.core.BasicItem

addUsingItems, addUsingItems, checkPermission, equals, getData, getDbControl, getId, getPermissions, getPluginPermissions, getSessionControl, getVersion, hashCode, hasPermission, initPermissions, isDetached, isInDatabase, onAfterCommit, onAfterInsert, onRollback, setDbControl, setProjectDefaults, toString, toTransferable, validate

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.sf.basedb.core.Identifiable

getId, getVersion

Methods inherited from interface net.sf.basedb.core.AccessControlled

checkPermission, getPermissions, hasPermission

Field Detail

TYPE

public static final Item TYPE

The type of item represented by this class.

See Also:

Item.UNIT, getType()

MAX_SYMBOL_LENGTH

public static final int MAX_SYMBOL_LENGTH

The maximum length of the display symbol that can be stored in the database.

See Also:

setDisplaySymbol(String), Constant Field Values

Constructor Detail

Unit

Unit(UnitData data)

Creates a unit item.

Parameters:

data - the data

Method Detail

getNew

public static Unit getNew(DbControl dc,
                          Quantity quantity,
                          String displaySymbol)
                   throws BaseException

Create a new Unit item. The unit will have default values for the reference factor (1.0) and offset (0.0). Use changeReferenceFactorAndOffset(double, double) to change those.

Parameters:

dc - The DbControl which will be used for permission checking and database access

quantity - The quantity the unit belongs to

displaySymbol - The symbol used when displaying values with this unit

Returns:

The new Unit item

Throws:

BaseException - If there is an error

getById

public static Unit getById(DbControl dc,
                           int id)
                    throws ItemNotFoundException,
                           PermissionDeniedException,
                           BaseException

Get a Unit object when you know the ID.

Parameters:

dc - The DbControl which will be used for permission checking and database access.

id - The system ID of the item to load.

Returns:

The Unit item

Throws:

ItemNotFoundException - This exception is thrown if an item with the specified ID is not found

PermissionDeniedException - This exception is thrown if the logged in user doesn't have read permission to the item

BaseException - This exception is thrown if there is another error

getQuery

public static ItemQuery<Unit> getQuery()

Get a query configured to retrieve units.

Returns:

An ItemQuery object

isUsed

public boolean isUsed()
               throws BaseException

Check if:

• Annotation types are using this unit as default unit
• Annotations are using this unit

Overrides:

isUsed in class BasicItem<UnitData>

Returns:

TRUE if this item is used, FALSE otherwise

Throws:

BaseException - If not able to tell if item is used or not.

See Also:

BasicItem.getUsingItems()

getUsingItems

public Set<ItemProxy> getUsingItems()

Get all:

• AnnotationType:s using this unit as default unit
• Annotation:s using this unit

  Overrides:

  getUsingItems in class BasicItem<UnitData>

  Returns:

  A set containing proxies for the items, or an empty set if no items are using this item

  See Also:

  BasicItem.addUsingItems(Set, Item, org.hibernate.Query)

onBeforeCommit

void onBeforeCommit(Transactional.Action action)
              throws BaseException

Set property filters that use this unit to null when the unit is deleted.

Overrides:

onBeforeCommit in class BasicItem<UnitData>

Throws:

BaseException - If there is an error

See Also:

Transactional, Core API overview - Transaction handling, Coding rules and guidelines for item classes

getType

public Item getType()

Description copied from interface: Identifiable

Get the type of item represented by the object. The returned value is one of the values defined in the Item enumeration.

Specified by:

getType in interface Identifiable

Returns:

A value indicating the type of item

isRemoved

public boolean isRemoved()

Description copied from interface: Removable

Check if the removed flag is set for this item.

Specified by:

isRemoved in interface Removable

Returns:

TRUE if the item is flagged as removed, FALSE otherwise

setRemoved

public void setRemoved(boolean removed)
                throws PermissionDeniedException

Description copied from interface: Removable

Set the removed flag for this item.

Specified by:

setRemoved in interface Removable

Parameters:

removed - TRUE if the item should be flagged as removed, FALSE otherwise

Throws:

PermissionDeniedException - If the logged in user doesn't have Permission.DELETE permission for setting the flag to TRUE or Permission.WRITE permission for setting the flag to FALSE

getName

public String getName()

Description copied from interface: Nameable

Get the name of the item.

Specified by:

getName in interface Nameable

Returns:

A String with the name of the item

setName

public void setName(String name)
             throws PermissionDeniedException,
                    InvalidDataException

Description copied from interface: Nameable

Set the name of the item. The name cannot be null and mustn't be longer than the value specified by the Nameable.MAX_NAME_LENGTH constant.

Specified by:

setName in interface Nameable

Parameters:

name - The new name for the item

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the name is null or longer than specified by the Nameable.MAX_NAME_LENGTH constant

getDescription

public String getDescription()

Description copied from interface: Nameable

Get the description for the item.

Specified by:

getDescription in interface Nameable

Returns:

A String with a description of the item

setDescription

public void setDescription(String description)
                    throws PermissionDeniedException,
                           InvalidDataException

Description copied from interface: Nameable

Set the description for the item. The description can be null but mustn't be longer than the value specified by the Nameable.MAX_DESCRIPTION_LENGTH constant.

Specified by:

setDescription in interface Nameable

Parameters:

description - The new description for the item

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the description longer than specified by the Nameable.MAX_DESCRIPTION_LENGTH constant

getQuantity

public Quantity getQuantity()

Get the quantity this unit belongs to.

setQuantity

private void setQuantity(Quantity quantity)

getDisplaySymbol

public String getDisplaySymbol()

Get the display symbol to use when displaying values with this unit.

Returns:

A String object

setDisplaySymbol

public void setDisplaySymbol(String symbol)
                      throws PermissionDeniedException,
                             InvalidDataException

Set the display symbol for this unit. The symbol is also registered as an alias symbol for this unit. The old symbol is NOT removed as an alias. Use removeSymbol(String) to do that.

Parameters:

symbol - The symbol

Throws:

PermissionDeniedException - If the logged in user doesn't have write permission

InvalidDataException - If the new value null or longer than MAX_SYMBOL_LENGTH

getSymbols

public Set<String> getSymbols()

Get all symbols that are registered for this unit.

Returns:

All symbols as a set

setSymbols

public void setSymbols(Set<String> symbols)

Set the symbols that should be registered for this unit. Note that all units must be unique within a given Quantity. Symbols that are not in the given set will be unregistered except for the display symbol.

Parameters:

symbols - A set with the symbols

addSymbol

public void addSymbol(String symbol)

Add a symbol to this unit.

Parameters:

symbol - The symbol to add

removeSymbol

public void removeSymbol(String symbol)

Remove a symbol from this unit. It is not possible to remove the display symbol.

Parameters:

symbol - The symbol to remove

getReferenceOffset

public double getReferenceOffset()

Get the offset that is used for converting values in this unit into the reference unit of the quantity. See Quantity.getReferenceUnit() for a description of how the values are converted.

Returns:

The reference offset

See Also:

changeReferenceFactorAndOffset(double, double)

getReferenceFactor

public double getReferenceFactor()

Get the factor that is used for converting values in this unit into the reference unit of the quantity. See Quantity.getReferenceUnit() for a description of how the values are converted.

Returns:

The reference factor

See Also:

changeReferenceFactorAndOffset(double, double)

changeReferenceFactorAndOffset

public void changeReferenceFactorAndOffset(double factor,
                                           double offset)

Changes the factor and offset used for converting values in this unit into the reference unit. Calling this method with values that are different from the old ones will result in a re-calculation of all annotation values that has used this unit to make sure that the actual values stays the same.

Parameters:

factor - The new factor

offset - The new offset

toReferenceUnit

public double toReferenceUnit(double value)

Convert a value from this unit to the reference unit.

Parameters:

value - The value in this unit

Returns:

The value converted to the reference unit

fromReferenceUnit

public double fromReferenceUnit(double value)

Convert a value from the reference unit to this unit.

Parameters:

value - The reference value

Returns:

The value converted to this unit

toUnit

public double toUnit(double value,
                     Unit other)

Convert a value from this unit to another unit. This method is equivalent to calling other.fromReferenceUnit(this.toReferenceUnit(value)).

Parameters:

value - The value in this unit

other - The other unit

Returns:

The value converted to the other unit

fromOther

public double fromOther(double value,
                        Unit other)

Convert a value from another unit to this unit. This method is equivalent to calling this.fromReferenceUnit(other.toReferenceUnit(value))

Parameters:

value - The value in the other unit

other - The other unit

Returns:

The value converted to this unit

getFormatter

public <T> Formatter<T> getFormatter(Formatter<T> parent)

Create a formatter for formatting values with this unit. The returned formatter delegates the formatting of the values to a parent formatter and uses a PrefixSuffixFormatter to append the unit symbol.

Parameters:

parent - The parent formatter for formatting the actual values

Returns:

The new formatter

findOtherUnit

UnitData findOtherUnit(org.hibernate.Session session,
                       String symbol)

Find the unit with a given symbol that has the same quantity as this unit.

Returns:

The unit, or null if no unit is found