/**
 *  Generated with Tigerstripe(tm) Tigerstripe Workbench Feature 2.2.0.v20070514-1108-IXOqsosF8y087t5.
 *
 *  Tigerstripe(tm) is a registered trademark of Tigerstripe, Inc.
 *
 *  Plugin  : Sun Microsystems Inc./SunJavaSpecificationPlugin(1.0) (1.0)
 *
 *  DO NOT EDIT THIS CODE WAS AUTOMATICALLY GENERATED
 *
 *  Generated from source Tigerstipe Artifact :
 *        javax.oss.cbe.CBEManagedEntity
 *
 *  Using template :
 *        templates/1.3/valueInterface.vm
 *
 * Copyright 2002-2007 The Members of the OSS through Java(TM) Initiative.
 * All rights reserved. Use is subject to license terms.
 */
package javax.oss.cbe;

import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
import javax.xml.bind.annotation.XmlType;

import ossj.common.cbe.CBEManagedEntityValueAdapter;

@XmlType
@XmlJavaTypeAdapter(value=CBEManagedEntityValueAdapter.class)

/**
 *  Public interface definition for CBEManagedEntityValue.
 *
 * This is the base for all the first class CBE Managed Entities
 *
 * These first class objects may be in one of the following categories:
 * <ul>
 * <li>entities
 * <li>entitiy specifications, describing entities
 * <li>associations, representing binary relationships between entities or
 * specifications
 * </ul>
 * CBEManagedEntityValue is the base value type interface for the CBE Entity,
 * Entity Specification and Association Values.
 *
 * <p>This interface extends the scope of the AttributeAccess interface to cover also the CharacteristicSpecifications of CBEManagedEntities. If a method in AttributeAccess worked on attributes only before, its semantic is now extended to handle characteristic specifications in an equal way. In that sense, characteristic specifications <b>are</b> attributes, but without a getter and setter. For example, {@link javax.oss.AttributeAccess#isFullyPopulated() isFullyPopulated} now only returns true if all static attributes and all characteristic specifications are populated; {@link javax.oss.AttributeAccess#getAttributeNames() getAttributeNames} returns the names of the static attributes (as previously) plus the names of the characteristic specifications.
 *
 * <P>When designing the characteristic specifications, the static attributes names are known to the designer, who has to take care that there must not be a name clash, means there must not be a static attribute and a characteristicSpecification with the same name.
 *
 * <p>The characterizedBy and describedBy fields allow to add attributes to a CBEManagedEntityValue without the need to change the interface. For example, bandwidth is characteristic of many different types of services; if bandwidth is important (e.g., from the point-of-view of a Customer purchasing this Service) then bandwidth would be a CharacteristicValue describing that particular Service.
 *
 * <p>In order to keep the CBEManagedEntityValue consistent, the array of CharacteristicSpecification returned by {@link #getCharacterizedBy} contains the exaustive list of supported attributes of the CharacteristicValue type.
 * The characterizedBy should be provided before the usage of {@link #setDescribedBy}.
 *
 * <p>A call to {@link #getDescribedBy} returns all CharateristicValues for this entity. CharacteristicValues could be returned or set individually by calling the generic {@link javax.oss.AttributeAccess#getAttribute} or {@link javax.oss.AttributeAccess#setAttribute} methods.
 *
 */
public interface CBEManagedEntityValue 
	extends javax.oss.ManagedEntityValue {

    /** VALUE_TYPE attribute name definition. */
    public static final String VALUE_TYPE = "javax.oss.cbe.CBEManagedEntityValue";
    
    /** attribute name definition for cBEManagedEntityKey.*/
    public static final String CBE_MANAGED_ENTITY_KEY = "cBEManagedEntityKey";


    /** attribute name definition for subGraphId. */
    public static final String SUB_GRAPH_ID = "subGraphId";
    /** attribute name definition for characterizedBy. */
    public static final String CHARACTERIZED_BY = "characterizedBy";
    /** attribute name definition for describedBy. */
    public static final String DESCRIBED_BY = "describedBy";

    /**
     * Deep copy of this object.
     *
     * @return The cloned object
     */
    public Object clone();


    /**
     *
     * Attribute getter for subGraphId.
     *
     *
     * Set the sub-graph ID. The sub-graph ID is set by the management system to
     * make possible the distinction of sub-graphs in a graph (e.g. the result
     * of a query may be better presented as a set of subgraphs instead of one
     * combined graph). The sub-graph ID is meaningful only in the context of a
     * concrete graph. This attribute is not persistently stored.
     *
     * @return the value of the subGraphId field.
     * @throws java.lang.IllegalStateException - if the attribute is not populated.
     *
     */
    public long getSubGraphId( )
        throws 
        java.lang.IllegalStateException;


    /**
     * Attribute setter for subGraphId.
     *
     *
     * Set the sub-graph ID. The sub-graph ID is set by the management system to
     * make possible the distinction of sub-graphs in a graph (e.g. the result
     * of a query may be better presented as a set of subgraphs instead of one
     * combined graph). The sub-graph ID is meaningful only in the context of a
     * concrete graph. This attribute is not persistently stored.
     * @param value - the value to use to set the subGraphId attribute.
     * @throws java.lang.IllegalArgumentException
     *         Thrown to report that a bad argument was provided to the method.
     *
     */
    public void setSubGraphId(long value)
        throws
        java.lang.IllegalArgumentException;

    /**
     *
     * Attribute getter for characterizedBy.
     *
     *
     * Contains the list of CharacteristicSpecification associated with this entity.
     *
     * @return the value of the characterizedBy field.
     * @throws java.lang.IllegalStateException - if the attribute is not populated.
     * @throws javax.oss.OssUnsupportedAttributeException - if the attribute is not supported.
     *
     */
    public javax.oss.cbe.CharacteristicSpecification[] getCharacterizedBy( )
        throws  
        java.lang.IllegalStateException,
        javax.oss.OssUnsupportedAttributeException;

    /**
     *
     * Attribute Type getter for characterizedBy.
     *
     * 
     * @return the valid set of types for the characterizedBy field.
     *
     */
    public String[] attributeTypeForCharacterizedBy();

    /**
     * Attribute setter for characterizedBy.
     *
     *
     * Contains the list of CharacteristicSpecification associated with this entity.
     * @param value - the value to use to set the characterizedBy attribute.
     * @throws java.lang.IllegalArgumentException
     *         Thrown to report that a bad argument was provided to the method.
     * @throws javax.oss.OssUnsupportedAttributeException - if the attribute is not supported.
     *
     */
    public void setCharacterizedBy(javax.oss.cbe.CharacteristicSpecification[] value)
        throws
        javax.oss.OssUnsupportedAttributeException,
        java.lang.IllegalArgumentException;

    /**
     *
     * Attribute getter for describedBy.
     *
     *
     * Contains the array of attribute values that describes the managed entity.
     * The description of this characteristic is available in the array of CharacteristicSpecification returned by a call to getCharacterizedBy() and corresponds
     * to the CharacteristicSpecification that have the same name attribute as the CharacteristicValue.getCharacteristic() attribute.
     * <p>
     * The IllegalArgumentException could be thrown if at least one of the specified characteristicValue.getCharacteristic() do not correspond to CharacteristicSpecification.getName().
     *
     * @return the value of the describedBy field.
     * @throws java.lang.IllegalStateException - if the attribute is not populated.
     * @throws javax.oss.OssUnsupportedAttributeException - if the attribute is not supported.
     *
     */
    public javax.oss.cbe.CharacteristicValue[] getDescribedBy( )
        throws  
        java.lang.IllegalStateException,
        javax.oss.OssUnsupportedAttributeException;

    /**
     *
     * Attribute Type getter for describedBy.
     *
     * 
     * @return the valid set of types for the describedBy field.
     *
     */
    public String[] attributeTypeForDescribedBy();

    /**
     * Attribute setter for describedBy.
     *
     *
     * Contains the array of attribute values that describes the managed entity.
     * The description of this characteristic is available in the array of CharacteristicSpecification returned by a call to getCharacterizedBy() and corresponds
     * to the CharacteristicSpecification that have the same name attribute as the CharacteristicValue.getCharacteristic() attribute.
     * <p>
     * The IllegalArgumentException could be thrown if at least one of the specified characteristicValue.getCharacteristic() do not correspond to CharacteristicSpecification.getName().
     * @param value - the value to use to set the describedBy attribute.
     * @throws java.lang.IllegalArgumentException
     *         Thrown to report that a bad argument was provided to the method.
     * @throws javax.oss.OssUnsupportedAttributeException - if the attribute is not supported.
     *
     */
    public void setDescribedBy(javax.oss.cbe.CharacteristicValue[] value)
        throws
        javax.oss.OssUnsupportedAttributeException,
        java.lang.IllegalArgumentException;


    /**
     * Factory method for CharacteristicSpecification.
     *
     * @param howMany - Number of instances to make
     * @param typeToMake - name of the type to be made
     * @return a new instance of CharacteristicSpecification
     *
     * @throws java.lang.IllegalArgumentException - if the argument is invalid
     */
    public javax.oss.cbe.CharacteristicSpecification[] makeCharacteristicSpecifications(int howMany , String typeToMake)
        throws 
        java.lang.IllegalArgumentException;


    /**
     * Factory method for CharacteristicValue.
     *
     * @param howMany - Number of instances to make
     * @param typeToMake - name of the type to be made
     * @return a new instance of CharacteristicValue
     *
     * @throws java.lang.IllegalArgumentException - if the argument is invalid
     */
    public javax.oss.cbe.CharacteristicValue[] makeCharacteristicValues(int howMany , String typeToMake)
        throws 
        java.lang.IllegalArgumentException;


    /**
     * Gets the key for this value object.
     *
     * @return the key for this value object
     * @throws java.lang.IllegalStateException if no key was populated in this
     *    value object.
     */
    public javax.oss.cbe.CBEManagedEntityKey getCBEManagedEntityKey()
        throws 
        java.lang.IllegalStateException;

    /**
     * Sets the key for this value object.
     *
     * @param key - the key to set on this value object.
     * @throws java.lang.IllegalArgumentException if the key is not a valid
     *    key for this value object.
     */
    public void setCBEManagedEntityKey(javax.oss.cbe.CBEManagedEntityKey key)
        throws 
        java.lang.IllegalArgumentException;

    /**
     * Factory method for CBEManagedEntityKey.
     *
     * @return a new instance of a blank CBEManagedEntityKey
     */
    public javax.oss.cbe.CBEManagedEntityKey makeCBEManagedEntityKey();

    /**
     * User specified method - isCharacteristic.
     *
     * This method helps the client to distinguish between static attributes,
     * i.e. those wich are defined in a java interface, and characteristics, which are the way SID models dynamic attributes.
     *
     * It returns true when the given name correspond to a CharacteristicSpecification.getName() of the characterizedBy attribute
     *
#optComm ( false )
     * @return boolean
     * @param characteristicSpecName - is compared to CharacteristicSpecification.getName() of the CharacteristicSpecifications list returned by getCharacterzedBy()
     *
     */
    public boolean isCharacteristic ( 
        java.lang.String characteristicSpecName);



}