ucar.units.UnitDB Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of udunits Show documentation
The ucar.units Java package is for decoding and encoding formatted unit specifications (e.g. "m/s"), converting numeric values between compatible units (e.g. between "m/s" and "knot"), and for performing arithmetic operations on units (e.g. dividing one unit by another, or raising a unit to a power).
The newest version!
/*
 * Copyright (c) 1998-2018 University Corporation for Atmospheric Research/Unidata
 * See LICENSE for license information.
 */
package ucar.units;

import java.util.Iterator;

/**
 * Interface for a unit database.
 * 
 * @author Steven R. Emmerson
 */
public interface UnitDB {
	/**
	 * Adds a unit to the database.
	 * 
	 * @param unit
	 *            The unit to be added. Its getName() method must not return
	 *            null. Its getPlural() and getSymbol() methods may return null.
	 * @throws NameException
	 *             Bad unit name.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 */
	public void addUnit(Unit unit) throws UnitExistsException,
			UnitDBAccessException, NameException;

	/**
	 * Adds an alias for a unit to the database.
	 * 
	 * @param alias
	 *            The alias for the unit.
	 * @param name
	 *            The name of the unit already in the database.
	 * @throws NameException
	 *             Bad unit name.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 * @throws NoSuchUnitException
	 *             The unit doesn't exist in the database.
	 */
	public void addAlias(String alias, String name) throws NoSuchUnitException,
			UnitExistsException, UnitDBAccessException, NameException;

	/**
	 * Adds an alias for a unit to the database.
	 * 
	 * @param alias
	 *            The alias for the unit.
	 * @param name
	 *            The name of the unit already in the database.
	 * @param symbol
	 *            The symbol for the unit.
	 * @throws NameException
	 *             Bad unit name.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 * @throws NoSuchUnitException
	 *             The unit doesn't exist in the database.
	 */
	public void addAlias(String alias, String name, String symbol)
			throws NoSuchUnitException, UnitExistsException,
			UnitDBAccessException, NameException;

	/**
	 * Adds an alias for a unit to the database.
	 * 
	 * @param alias
	 *            The alias for the unit.
	 * @param name
	 *            The name of the unit already in the database.
	 * @param symbol
	 *            The symbol of the alias. May be null
     *				.
	 * @param plural
	 *            The plural form of the alias. May be 
     *				null in which
	 *            case regular plural- forming rules are followed.
	 * @throws NameException
	 *             Bad unit name.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 * @throws NoSuchUnitException
	 *             The unit doesn't exist in the database.
	 */
	public void addAlias(String alias, String name, String symbol, String plural)
			throws NoSuchUnitException, UnitExistsException,
			UnitDBAccessException, NameException;

	/**
	 * Adds an alias for a unit to the database.
	 * 
	 * @param id
	 *            The alias identifier.
	 * @param name
	 *            The name of the unit already in the database.
	 * @throws NoSuchUnitException
	 *             The unit doesn't exist in the database.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 */
	public void addAlias(UnitID id, String name) throws NoSuchUnitException,
			UnitExistsException, UnitDBAccessException;

	/**
	 * Adds a symbol for a unit to the database.
	 * 
	 * @param symbol
	 *            The symbol for the unit.
	 * @param name
	 *            The name of the unit already in the database.
	 * @throws NameException
	 *             Bad unit name.
	 * @throws UnitExistsException
	 *             The unit is already in the database.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 * @throws NoSuchUnitException
	 *             The unit doesn't exist in the database.
	 */
	public void addSymbol(String symbol, String name)
			throws NoSuchUnitException, UnitExistsException,
			UnitDBAccessException, NameException;

	/**
	 * Gets the unit in the database whose name, plural, or symbol, match an
	 * identifier. The order of matching is implementation defined.
	 * 
	 * @param id
	 *            The identifier for the unit.
	 * @return The matching unit in the database or 
     *				null if no
	 *         matching unit could be found.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 */
	public Unit get(String id) throws UnitDBAccessException;

	/**
	 * Gets a unit in the database by name.
	 * 
	 * @param name
	 *            The name of the unit.
	 * @return The matching unit in the database or 
     *				null if no
	 *         matching unit could be found.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 */
	public Unit getByName(String name) throws UnitDBAccessException;

	/**
	 * Gets a unit in the database by symbol.
	 * 
	 * @param symbol
	 *            The symbol for the unit.
	 * @return The matching unit in the database or 
     *				null if no
	 *         matching unit could be found.
	 * @throws UnitDBAccessException
	 *             Problem accessing unit database.
	 */
	public Unit getBySymbol(String symbol) throws UnitDBAccessException;

	/**
	 * Returns the string representation of the database.
	 * 
	 * @return The string representation of the database.
	 */
	public String toString();

	/**
	 * Returns an iterator over the units of the database.
	 * 
	 * @return An iterator over the units of the database. The
	 *         next() of the iterator returns objects of type
	 *         Unit.
	 */
	public Iterator getIterator();
}