//
// Copyright (c)1998-2011 Pearson Education, Inc. or its affiliate(s).
// All rights reserved.
//
package openadk.library;
import java.util.List;
/**
* Encapsulates metadata for a SIF element or attribute.<p>
*
* The ElementDef interface is fundamental to programming with the ADK. It's
* primarily used internally for parsing and rendering of SIF Data Objects across
* all versions of the SIF Specification, but is also used by in ADK programming to
* uniquely identify SIF Data Objects, elements, and attributes.<p>
*
* An instance of ElementDef captures the following characteristics of each XML
* element and attribute in the SIF data model:<p>
*
* <ul>
* <li>The internal ADK name of the element/attribute</li>
* <li>The version-dependent tag name of the element/attribute</li>
* <li>The first version of SIF the element/attribute appears in</li>
* <li>The version-dependent sequence number of the element/attribute</li>
* <li>Flags, such as whether an element is repeatable</li>
* </ul>
*
* @author Eric Petersen
* @version 1.0
*/
public interface ElementDef
{
/**
* Gets the version-independent name of this element or attribute. To get
* the actual tag name, which is SIF version-dependent, call the <code>tag</code>
* method.<p>
*
* @return The version-independent name, which is usually equal to the
* element or attribute name in SIF 1.0r1, the first version of the
* SIF Specification supported by the SDO framework
*
* @see #tag
*/
public String name();
/**
* Returns the type converter suitable for parsing the SIF XML value
* into the proper datatype
* @return a SIFTypeConverter
*/
public SIFTypeConverter getTypeConverter();
/**
* Gets version-specific information for this element
* @param version Identifies the version of SIF to return the version information for
* @return version-specific information for this element
*/
public ElementVersionInfo getVersionInfo( SIFVersion version );
/**
* Gets the tag name
* @param version Identifies the version of SIF to return the tag name for
* @return The element tag or attribute name specific to this version of SIF
*/
public String tag( SIFVersion version );
/**
* Gets the sequence number
* @param version Identifies the version of SIF to return the sequence number for
* @return The element sequence number for this version of SIF
*/
public int sequence( SIFVersion version );
/**
* Constructs a path to this ElementDef object, comprised of the names of
* its ancestry delimited by an underscore. The path can be used to lookup
* an ElementDef object via the <code>SIFDTD.lookupMetaData</code> method.
* Note the strings used in the path generated by this method are not
* necessarily the same as the element or attribute tag names used in SIF
* XML messages. Rather, they are version-independent names typically equal
* to the tag name of the element in SIF 1.0r1.<p>
*
* @return A path string (e.g. "StudentPersonal_RefId")
*/
public String getSDOPath();
/**
* Constructs a path to this element/attribute in the SIF Query Pattern
* format. The path is comprised of element tag and attribute names, which
* are dependent on the version of SIF specified. The root-level SIF Data
* Object element is excluded from the path.<p>
*
* @param version Identifies the version of SIF to return the path for
* @return A path to this element/attribute (e.g. "@RefId", "Email/@Type", etc.)
*/
public String getSQPPath( SIFVersion version );
/**
* Gets the parent metadata object, or null if this metadata describes
* a root-level SIF Data Object element
* @return The parent metadata object
*/
public ElementDef getParent();
/**
* Gets all of metadata objects defined as children of this metadata object
* @return The child metadata objects
*/
public List<ElementDef> getChildren();
/**
* Gets the root metadata object
* @return The root metadata object
*/
public ElementDef getRoot();
/**
* The name of the class that encapsulates elements of this type.<p>
* @return The implementation class name excluding package information
* @see #getFQClassName
*/
public String getClassName();
/**
* Gets the fully-qualified Java class name of the class that encapsulates
* elements of this type.<p>
* @return The implementation class name including package information
* @see #getClassName
* @see #getPackage
*/
public String getFQClassName();
/**
* Gets the package of the class that encapsulates elements of this type.<p>
* @return The Java package name where the implementation class is found
* @see #getFQClassName
*/
public String getPackage();
/**
* Gets the element sequence number
* @param version The SIF Version to retrieve the sequence number for
* @return The zero-based sequence number of this element
*/
public int getSequence( SIFVersion version );
/**
* Determines if this metadata describes an XML attribute
* @param version The SIFVersion to use when checking if this object is an attribute
* @return true if this metadata describes an XML attribute
*/
public boolean isAttribute( SIFVersion version );
/**
* Determines if this metadata describes a SIF <i>field</i>; that is, an
* element that has no children
* @return True if this element is a field of its parent
*/
public boolean isField();
/**
* Determines if this metadata describes a root-level SIF Data Object
* @return True if this element represents a topic (e.g. StudentPersonal)
*/
public boolean isObject();
/**
* Determines if this metadata describes an element that is contained in the
* specified version of SIF.
*
* @param version The version of the SIF Specification
* @return <code>TRUE</code> if the metadata is included in the specified version of SIF
*/
public boolean isSupported( SIFVersion version );
/**
* Determines if this metadata describes a deprecated element or attribute
* in this version of SIF
* @param version The SIFVersion to check
* @return True if this element is deprecated in the specified version of SIF
*/
public boolean isDeprecated( SIFVersion version );
/**
* Determines if this metadata describes a repeatable element in this version of SIF
* @param version The SIF version to check
* @return True if the element is repeatable in the specified version of SIF
*/
public boolean isRepeatable( SIFVersion version );
/**
* Determines if this element should not be written in this version of SIF, but that rather
* it's children should be written in it's place. This is helpful for cases where a set of
* elements valid for one version of SIF were moved inside of a new container element in
* a subsequent version (e.g. StudentPersonal/Email )
* @param version
* @return True if the element is collapsed in the specified version of SIF
*/
public boolean isCollapsed( SIFVersion version );
/**
* Determines if the content of this element can be automatically encoded
* when written to an output stream by the SIFWriter class when automatic
* encoding is enabled (the default behavior in ADK 1.5.1.0 and later).
* Encoding converts all invalid XML characters to valid XML entities.
* Some elements contain XML content and should not be encoded.
* @return True if the element should not have XML encoding applied
*/
public boolean isDoNotEncode();
/**
* Gets the earliest version of SIF that supports the element or attribute
* described by this metadata
* @return The first SIFVersion this element appeared in
*/
public SIFVersion getEarliestVersion();
/**
* Gets the latest version of SIF that supports the element or attribute
* described by this metadata
* @return The latest SIFVersion this element appeared in
*/
public SIFVersion getLatestVersion();
/**
* Add a version-specific definition of the tag to this ElementDef.<p>
*
* @param version A SIFVersion constant (other than SIF10r1, which is
* implicitly defined by all ElementDef class constructors)
* @param tag The element tag name for this version of SIF
* @param sequence The sequence number for this version of SIF
* @param flags One or more flags such as <code>FD_DEPRECATED</code>
*/
public void defineVersionInfo( SIFVersion version, String tag, int sequence, int flags );
/**
* Returns true if the element referenced contains simple content, such as a string or int
* @return True if this element represents simple content
*/
public boolean hasSimpleContent();
}