/*
 * Created on 08 December 2005, 12:48
 *
 * (C) 2005 Copyright ANSTO. All rights reserved.
 */

package au.gov.ansto.bragg.nexus.base;

//import au.gov.ansto.bragg.base.entity.EntityBean;

/** The root interface of the NeXusBeans hierarchy.
 * 
 * <p>All NeXusBean interfaces extend this.</p>
 * <p>All NexusBean classes implement this.</p>
 *
 * <p>
 * <b>History:</b> in Feb 2006 at NIAC 2006 in Grenoble I presented
 * the NeXusBeans concept. I made the case that the use 
 * of polymorphism via inheritance is crucial to advancement of
 * the NeXus effort, and that such inheritance should be managed
 * using industry standard notations and data modelling tools
 * (such as Unified Modelling Language (UML)), and that the
 * NeXus artefacts SHOULD be represented in forms that enable
 * interaction with industry standard tools, and automated generation
 * of NeXus components in many required languages. The NeXusBean
 * system with the NXobject introduced by Darren Kelly of ANSTO 
 * meets that need.
 * </p>
 * 
 * <p>
 * NB: Although this base is represented in Java, all of the principles
 * documented here find equivalents in XML Schema management, in fact
 * this system DOES map identically to an XML Schema (to the extent
 * that the sometimes cryptic NeXus meta-DTD specifications can be interpreted).
 * </p>
 *
 * <p>
 * 2007-02-05 Decision: Rather than extending the au.gov.ansto.bragg.entity.EntityBean
 * to integrate it into Darren Kelly's instrospective BraggBean framework,
 * it has been decided to offer this as a standalone root interface,
 * so that NeXus users can use the NeXusBeans library independently.
 * Instead, integration into the BraggBean framework at ANSTO will be achieved 
 * as ANSTO using wrappers (an 'adapter' that makes an NXobject look like a bragg.EntityBean
 * to the BraggBean framework).
 * </p>
 *
 * @author Darren Kelly (Bragg Institute)
 */
public interface NXobject 
//        extends EntityBean
{
    /** A placeholder for undefined quantities to afford feedback and diagnostics.
     */
    String $UNDEF = "UNDEF";

    /** The (archetypal) attribute property helper string for 'name'.
     *
     * <p>This strategy, employed throughout Darren Kelly's
     * Bragg APIs, affords assistance to bean developers.
     * Bean operations requiring string identifiers
     * can use this rather than hand-typed, error prone, inline strings.
     * </p>
     *
     * <p>
     * For example, property change notifications requiring
     * the property name as a string SHOULD use this property string,
     * and prompting on the '$' in a modern IDE is convenient for this purpose.
     * </p>
     *
     * <p>
     * While slightly expensive during property lookups, the gains afforded justify it,
     * and in practise it has proved very efficient, robust, and helpful.
     * (It can also be supplemented with EMF-style integer indexed properties anyway.)
     * </p>
     *
     * <p>The same pattern is employed through the auto generated NeXusBeans.</p>
     */
    String $name = "name";
    
    /** The programmatic name of this.
     *
     * <p><b>History:</b> Rather than declaring that each and
     * every 'component' specified in a NeXus XML templates 
     * (a.k.a. meta-DTD) be tediously documented with its own
     * name, I insist that such common attributes SHOULD be
     * declared in root (or relative root) classes.
     * </p>
     */
    String getName();

    /** <b>metadoc:</b> Only exceptional circumstances need be documented in setters ! */
    void setName(String name);

    /** The persistent Object identifier of this.
     * 
     * <p>It is planned that NeXusBeans will be made hibernatable
     * through Hibernate annotations; this ID is the unique Object identifier
     * that would be delivered by the persistence engine.
     * </p>
     *
     * <p>
     * Alternative implementations may likewise use this
     * as the persistent object identifier.
     * </p>
     *
     */
    Object getId();
    
    /** DO NOT use this to set the identifier unless you have 
     * a reliable persistence engine to ensure its uniqueness within a persistence context !
     */
    void setId(Object id);
}
