us.gov.dod.standard.ssrf

Class SSRFUtility

java.lang.Object

us.gov.dod.standard.ssrf.SSRFUtility

public class SSRFUtility
extends Object

A collection of useful SSRF and JAXB Utility classes.

These methods help to assemble, validate, serialize and un-serialize object representations to and from XML.

Since:

3.1.0

Version:

1.0, 10/02/14

Author:

Jesse Caulfield

Constructor Summary

Constructors

Constructor and Description
SSRFUtility()

Method Summary

Modifier and Type	Method and Description
static Set<String>	evaluate(Object instance) Evaluate a SSRF Object instance; record and report any configuration errors.
static Set<Field>	findDeclaredAndInheritedFields(Class<?> clazz) Get all declared and inherited fields from a class type.
protected static Set<Method>	findDeclaredAndInheritedMethods(Class<?> clazz) Get all declared and inherited methods from a class type.
protected static Method	findGetMethod(Class<?> clazz, Field field) Helper method to inspect the indicated Class to find the first declared or inherited GET setter method for the indicated field type.
protected static Method	findSetMethod(Class<?> clazz, Field field) Helper method to inspect the indicated Class to find the first declared or inherited SET setter method for the indicated field type.
protected static Method	findWithCollectionMethod(Class<?> clazz, Field field) Helper method to inspect the indicated Class to find the declared or inherited WITH setter method for the indicated field type that accepts a SET.
protected static Method	findWithEnumMethod(Class<?> clazz, Field field) Helper method to inspect the indicated Class to find the declared or inherited WITH setter method for the indicated field type that accepts a SET.
protected static Method	findWithMethod(Class<?> clazz, Field field) Helper method to inspect the indicated Class to find the first declared or inherited WITH setter method for the indicated field type.
protected static boolean	isRequired(Field field) Inspect a class field and determine if it is required.
protected static boolean	isTransient(Field field) Inspect a class field and determine if it is TRANSIENT - e.g.
static <T> String	marshal(T clazz) Marshal an entity class into a XML String representation.
static BigInteger	nextIndex() Get the next guaranteed unique index compatible with SSRF "idx" fields.
static SSRF	postLoad(SSRF ssrf) Process a SSRF instance object after reading from XML.
static void	prepare(Object sourceInstance, Object rootInstance) Process a SSRF instance object for export (recursive, internal).
static SSRF	prepare(SSRF ssrf) Process a SSRF instance object for export.
static void	setProperties(SSRFProperties properties, Object instance) Assign a SSRF Properties configuration to a SSRF object instance.
static <T> T	unmarshal(String xml, Class<T> clazz) Parse an XML file into a container class.
static void	validate(Object instance) Validate a SSRF object instance.
static void	validate(Object instance, ListCCL cls) Validate a SSRF object instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SSRFUtility

public SSRFUtility()

Method Detail

nextIndex

public static BigInteger nextIndex()

Get the next guaranteed unique index compatible with SSRF "idx" fields. * The returned value is monotonically incremented by one from the previously provided value.

All values increment from a randomly selected start value unique to each SSRFUtility instantiation.

This method is required by the following 9 classes which set an index in their constructors: Comment, ConfigFreq, Curve, Ellipse, ExtReferenceRef, Footnote, Point, Polygon, Remarks,

Returns:

an AtomicInteger, wrapped inside a BigInteger instance.

validate

public static void validate(Object instance)
                     throws Exception

Validate a SSRF object instance.

This method keeps track of the instance parent instance, plus the field within that parent instance where the current object instance is set. These are tracked to help produce a set of legible error messages.

Developer note: For more information about Java reflection see The Reflection API and Java Reflection Tutorial.

Parameters:

instance - the object instance to validate

Throws:

Exception - if the SSRF instance fails to validate

validate

public static void validate(Object instance,
                            ListCCL cls)
                     throws Exception

Validate a SSRF object instance. (internal, recursive)

This method keeps track of the instance parent instance, plus the field within that parent instance where the current object instance is set. These are tracked to help produce a set of legible error messages.

Developer note: For more information about Java reflection see The Reflection API and Java Reflection Tutorial.

Parameters:

instance - the object instance to validate

cls - The parent (maximum) classification. If set all subordinate classifications in the class tree must be less than or equal to this value.

Throws:

Exception - if the SSRF instance fails to validate

evaluate

public static Set<String> evaluate(Object instance)

Evaluate a SSRF Object instance; record and report any configuration errors.

This method recursively validates the provided object instance and all of its components. The validation procedure ensures that all required fields are set and that all configured fields contain valid data according to the SSRF data formatting rules.

If the SSRF object instance does not validate OK then each specific validation error condition is recorded and returned.

It is expected that this method will only be called on the top-level SSRF class. However it will just as easily validate any SSRF data type.

Parameters:

instance - the object instance to validate

Returns:

a non-null Collection of error messages. The collection is EMPTY if the object instance validates OK.

findDeclaredAndInheritedFields

public static Set<Field> findDeclaredAndInheritedFields(Class<?> clazz)

Get all declared and inherited fields from a class type.

Reflection does not expose inherited fields. This method implements a recursive search (up to but not including the base Object) of the Class inheritance tree and returns all declared fields.

Parameters:

clazz - the class type to inspect

Returns:

a non-null HashSet instance of Fields

findDeclaredAndInheritedMethods

protected static Set<Method> findDeclaredAndInheritedMethods(Class<?> clazz)

Get all declared and inherited methods from a class type.

Reflection does not expose inherited fields. This method implements a recursive search (up to but not including the base Object) of the Class inheritance tree and returns all declared methods.

Parameters:

clazz - the class type to inspect

Returns:

a non-null HashSet instance of Methods

isRequired

protected static boolean isRequired(Field field)

Inspect a class field and determine if it is required.

This method looks for and inspects XmlAttribute, XmlElement and XmlElementRef field annotation types marked as REQUIRED; also, XmlValue.

Parameters:

field - the field to inspect

Returns:

TRUE if and only if the XML annotation is marked "required = true"

isTransient

protected static boolean isTransient(Field field)

Inspect a class field and determine if it is TRANSIENT - e.g. should NOT be processed .

This method looks for a XmlTransient field annotation.

Parameters:

field - the field to inspect

Returns:

TRUE if and only if the XML annotation is marked "required = true"

prepare

public static SSRF prepare(SSRF ssrf)

Process a SSRF instance object for export.

This method examines the class tree and copies all required data objects into their proper location and prepares the SSRF destination instance for export.

Parameters:

ssrf - A SSRF working copy

Returns:

The input SSRF instance after preparation. The live object is returned to support method chaining.

prepare

public static void prepare(Object sourceInstance,
                           Object rootInstance)

Process a SSRF instance object for export (recursive, internal).

This method examines the class tree and copies all required data objects into their proper location and prepares the SSRF destination instance for export.

Parameters:

sourceInstance - the current object instance to inspect

rootInstance - the root SSRF/SMADEF object instance into which the source instance components are copied

postLoad

public static SSRF postLoad(SSRF ssrf)

Process a SSRF instance object after reading from XML.

This method examines the class tree and copies all required data objects into their proper location and preparing the SSRF software class hierarchy for working.

Parameters:

ssrf - a SSRF instance

Returns:

The input SSRF instance after post-load. The live object is returned to support method chaining.

setProperties

public static void setProperties(SSRFProperties properties,
                                 Object instance)

Assign a SSRF Properties configuration to a SSRF object instance.

This assigns default values declared in a SSRF configuration profile to a SSRF configuration.

Parameters:

properties - a SSRF properties configuration

instance - a SSRF object instance. The field type is a generic object as this method calls itself recursively.

findWithMethod

protected static Method findWithMethod(Class<?> clazz,
                                       Field field)

Helper method to inspect the indicated Class to find the first declared or inherited WITH setter method for the indicated field type.

This method supports setProperties(SSRFProperties, java.lang.Object).

Parameters:

clazz - the class type to inspect

field - the field to look for

Returns:

a WITH setter method, if present

findWithCollectionMethod

protected static Method findWithCollectionMethod(Class<?> clazz,
                                                 Field field)

Helper method to inspect the indicated Class to find the declared or inherited WITH setter method for the indicated field type that accepts a SET.

This method supports setProperties(SSRFProperties, java.lang.Object).

Parameters:

clazz - the class type to inspect

field - the field to look for

Returns:

a WITH setter method, if present

findWithEnumMethod

protected static Method findWithEnumMethod(Class<?> clazz,
                                           Field field)

Helper method to inspect the indicated Class to find the declared or inherited WITH setter method for the indicated field type that accepts a SET.

This method supports setProperties(SSRFProperties, java.lang.Object).

Parameters:

clazz - the class type to inspect

field - the field to look for

Returns:

a WITH setter method, if present

findSetMethod

protected static Method findSetMethod(Class<?> clazz,
                                      Field field)

Helper method to inspect the indicated Class to find the first declared or inherited SET setter method for the indicated field type.

Parameters:

clazz - the class type to inspect

field - the field to look for

Returns:

a SET setter method, if present

findGetMethod

protected static Method findGetMethod(Class<?> clazz,
                                      Field field)

Helper method to inspect the indicated Class to find the first declared or inherited GET setter method for the indicated field type.

Parameters:

clazz - the class type to inspect

field - the field to look for

Returns:

a SET setter method, if present

marshal

public static <T> String marshal(T clazz)
                          throws JAXBException

Marshal an entity class into a XML String representation.

The output of this method is typically either written to a file or sent via a SOAP communication link.

Type Parameters:

T - the entity class type

Parameters:

clazz - the entity class to be written

Returns:

the entity class serialized into XML form

Throws:

JAXBException - if the entity class cannot be marshaled (serialized)

unmarshal

public static <T> T unmarshal(String xml,
                              Class<T> clazz)
                       throws JAXBException

Parse an XML file into a container class. This method calls the JAXB un-marshaler and returns a class containing all of the content defined in the XML file.

Type Parameters:

T - the class type to be returned

Parameters:

xml - the XML source content

clazz - the parsed and populated class type; this is the same as the class type that is returned

Returns:

the XML source file parsed into the identified class type

Throws:

JAXBException - if the XML source file does not match the input class type