/**
 *  Generated with Tigerstripe(tm) Tigerstripe Workbench Feature 2.2.0.v20070419-1556-GFEkmUll2-0111E.
 *
 *  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.Association
 *
 *  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.AssociationValueAdapter;

@XmlType
@XmlJavaTypeAdapter(value=AssociationValueAdapter.class)

/**
 *  Public interface definition for AssociationValue.
 *
 * The <CODE>AssociationValue</CODE> is the base from which all association
 * interfaces are derived.
 * <p>
 * Associations are represented in the CBE package as managed entities
 * (according to the OSS through Java definition of managed entity).
 * <CODE>Association</CODE> instances have their own keys.
 *
 * <p>
 * The following attributes of an <CODE>AssociationValue</CODE> are set at creation:
 * <ul>
 * <li>EntityKey
 * <li>the key of object A (A end)
 * <li>the key of object Z (Z end)
 * </ul>
 * Note that other attributes could be defined by concrete association values
 * derived from this base interface. However these attributes should be specific
 * to this association and should not depend on the state of other objects.
 * <p>
 * The roles are captured in the definition of the association attributes
 * and in the corresponding {@link AssociationRule AssociationRule}.
 * For example in a "<CODE>SupportedBy</CODE>" type of association for one of the
 * objects will be defined an attribute "<CODE>supporting</CODE>" and "<CODE>supported</CODE>" for the other.
 * The corresponding <CODE>AssociationRule</CODE> will define the A and Z end roles as
 * "<CODE>supporting</CODE>" and "<CODE>supported</CODE>".
 * <p>
 * An {@link AssociationRule AssociationRule} is provided for every concrete
 * association type. The rule defines the constraints for this association type
 * (e.g. roles, cardinality, association constraints).
 * <p>
 * Associations are uniquely identified by their keys.
 * See {@link AssociationKey AssociationKey}
 * for more information.
 * <p>
 * The <CODE>AssociationValue</CODE> inherits from <CODE>ManagedEntityValue</CODE> all methods
 * for population, generic attribute access and serialization.
 *
 */
public interface AssociationValue 
	extends javax.oss.cbe.CBEManagedEntityValue {

    /** VALUE_TYPE attribute name definition. */
    public static final String VALUE_TYPE = "javax.oss.cbe.AssociationValue";
    
    /** attribute name definition for associationKey.*/
    public static final String ASSOCIATION_KEY = "associationKey";


    /** attribute name definition for AEndKey. */
    public static final String A_END_KEY = "AEndKey";
    /** attribute name definition for ZEndKey. */
    public static final String Z_END_KEY = "ZEndKey";

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


    /**
     *
     * Attribute getter for AEndKey.
     *
     *
     * Sets the key for the A end of the Association.
     *
     * @return the value of the AEndKey field.
     * @throws java.lang.IllegalStateException - if the attribute is not populated.
     *
     */
    public javax.oss.cbe.EntityKey getAEndKey( )
        throws 
        java.lang.IllegalStateException;

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

    /**
     * Attribute setter for AEndKey.
     *
     *
     * Sets the key for the A end of the Association.
     * @param value - the value to use to set the AEndKey attribute.
     * @throws java.lang.IllegalArgumentException
     *         Thrown to report that a bad argument was provided to the method.
     *
     */
    public void setAEndKey(javax.oss.cbe.EntityKey value)
        throws
        java.lang.IllegalArgumentException;

    /**
     *
     * Attribute getter for ZEndKey.
     *
     *
     * Sets the key for the Z end of the Association.
     *
     * @return the value of the ZEndKey field.
     * @throws java.lang.IllegalStateException - if the attribute is not populated.
     *
     */
    public javax.oss.cbe.EntityKey getZEndKey( )
        throws 
        java.lang.IllegalStateException;

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

    /**
     * Attribute setter for ZEndKey.
     *
     *
     * Sets the key for the Z end of the Association.
     * @param value - the value to use to set the ZEndKey attribute.
     * @throws java.lang.IllegalArgumentException
     *         Thrown to report that a bad argument was provided to the method.
     *
     */
    public void setZEndKey(javax.oss.cbe.EntityKey value)
        throws
        java.lang.IllegalArgumentException;


    /**
     * Factory method for Entity.
     *
     * @param typeToMake - name of the type to be made
     * @return a new instance of Entity
     *
     * @throws java.lang.IllegalArgumentException - if the argument is invalid
     */
    public javax.oss.cbe.EntityKey makeEntityKey(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.AssociationKey getAssociationKey()
        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 setAssociationKey(javax.oss.cbe.AssociationKey key)
        throws 
        java.lang.IllegalArgumentException;

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


}