org.hd.d.pg2k.svrCore.location
Class Location.Base

java.lang.Object
  org.hd.d.pg2k.svrCore.location.Location.Base

All Implemented Interfaces:

java.io.Serializable, MemoryTools.Internable

Direct Known Subclasses:

Location.None, Location.Time

Enclosing class:

Location

public abstract static class Location.Base
extends java.lang.Object
implements java.io.Serializable, MemoryTools.Internable

Base of all location classes. All such classes contain an optional time value (with error bounds), and flag to indicate if this location information was specific to this collection item, or applied to a group of items.

A true value for `specific' says that the item had its own time info rather than inheriting a general value.

If the time value is zero it indicates that none is known. (If the time value is zero, so should its error bound be.)

All classes derived from this should be immutable and serialisable and support equals() and hashCode().

TODO: should do validation on deserialisation.

See Also:

Serialized Form

type

public final java.lang.String type

The type of this location info.

specific

public final boolean specific

Did this item have its own specific location info?

typeKey

public static final java.lang.String typeKey

Name of key giving location type in Properties map.

See Also:

Constant Field Values

specificKey

public static final java.lang.String specificKey

Name of key giving specificity in Properties map.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

Location.Base

protected Location.Base(boolean _specific,
                        java.lang.String prefix,
                        java.util.Properties p)
                 throws PGException

Build new base from properties. Looks for the type field, which must be present, and the optional time fields.

Note that the _specific parameter is overridden where a `specific' property is present.

Package-visible to restrict the range of derived classes.

Parameters:

_specific - is true if the location info was specifically for this item, else false to indicate that this location info was inherited from some more general source

Throws:

PGException

hashCode

public int hashCode()

Hash depends on type and "specific" flag.

Overrides:

hashCode in class java.lang.Object

equals

public boolean equals(java.lang.Object obj)

Hash depends on equality of type and "specific" flags. A derived class should probably make use of this recursively.

Overrides:

equals in class java.lang.Object

toString

public java.lang.String toString()

Generate terse, human readable portion of location info. This should be overridden by derived classes, but with this used (via super.toString()) to generate the prefix for the result.

The string generated by this routine contains no white space to make the result handlable as one token and is shell- and HTML- friendly, with portions separated by colons, and deriving classes must abide by this too.

This generates a string consisting of the type name followed by a colon then `s' for a specific location or `g' for a generic one.

Overrides:

toString in class java.lang.Object

buildFromProperties

public static Location.Base buildFromProperties(boolean specific,
                                                java.lang.String prefix,
                                                java.util.Properties p)
                                         throws PGException

Factory method to build a class from a property set; never returns null. The Properties map passed is only read (not updated), and consists of a number of keys prefixed with the given prefix (either the empty string, or a fully-qualified name prefix, ending with ".").

Whatever type of map is being built, there must always be the key given by the prefix + typeKey, which must contain the type of location info, and that type must be the name of the class in this Location outer class, derived from Base, that holds the location info.

For robustness, if we cannot use the location info for some reason, we should probably pretend that the item has none, though flag the problem to stderr.

Throws:

PGException - in case of inability to build a location value from the specified properties

buildFromProperties

public static Location.Base buildFromProperties(boolean specific,
                                                java.util.Properties p)
                                         throws PGException

Build from properties with empty prefix.

Throws:

PGException

buildFromFile

public static Location.Base buildFromFile(boolean specific,
                                          java.io.File f)
                                   throws java.io.IOException,
                                          PGException

Build directly from a file, assuming empty prefix.

Throws:

java.io.IOException

PGException

buildFromFileOrNONE

public static Location.Base buildFromFileOrNONE(boolean specific,
                                                java.io.File f)

Attempts to build location from file. Returns Location.NONE type in case of difficulty.

getDoubleProp

public static final java.lang.Double getDoubleProp(java.lang.String prefix,
                                                   java.util.Properties p,
                                                   java.lang.String prop,
                                                   boolean rejectNegative)
                                            throws PGException

Routine to get a double property. Throws a PGException if there is a problem.

Can be asked to veto negative values, eg for error margins.

Throws:

PGException

getDoubleProps

public static final Location.DoubleValueAndBounds getDoubleProps(java.lang.String prefix,
                                                                 java.util.Properties p,
                                                                 java.lang.String prop,
                                                                 boolean manditory)
                                                          throws PGException

Get pair of double properties; requested one and its error interval. If the specified property is X, the main property is XErr.

If manditory and either property is missing, a PGException is thrown.

If optional and the first property is missing, null is returned; but if the first property is present and the second is absent then a PGException is thrown.

Throws:

PGException

getBooleanProp

public static final java.lang.Boolean getBooleanProp(java.lang.String prefix,
                                                     java.util.Properties p,
                                                     java.lang.String prop,
                                                     boolean manditory)
                                              throws PGException

Routine to get a boolean property. Throws a PGException if there is a problem.

Throws:

PGException

getLongProp

public static final java.lang.Long getLongProp(java.lang.String prefix,
                                               java.util.Properties p,
                                               java.lang.String prop,
                                               boolean rejectNegative)
                                        throws PGException

Routine to get a double property. Throws a PGException if there is a problem.

Can be asked to veto negative values, eg for error margins.

Throws:

PGException

getLongProps

public static final Location.LongValueAndBounds getLongProps(java.lang.String prefix,
                                                             java.util.Properties p,
                                                             java.lang.String prop,
                                                             boolean manditory)
                                                      throws PGException

Get pair of long properties; requested one and its error interval. If the specified property is X, the main property is XErr.

If manditory and either property is missing, a PGException is thrown.

If optional and the first property is missing, null is returned; but if the first property is present and the second absent a PGException is thrown.

Throws:

PGException