// AID-GENERATED
// =========================================================================
// This class was generated by AID - Abstract Interface Definition          
// DO NOT MODIFY, but use the org.freehep.aid.Aid utility to regenerate it. 
// =========================================================================

// Copyright 2000-2004, FreeHEP.
package hep.graphics.heprep;

import java.util.List;

/**
 * HepRepInstance interface.
 *
 * @author Mark Donszelmann
 */
public interface HepRepInstance extends HepRepAttribute {

    /**
     * Overlays the instance on the current instance.
     *
     * Attributes of the instance override or are added to the current instance.
     * Sub-instances of the instance are added only if the current instance has no sub-instances.
     * Points of the instance are added only if the current instance has no points.
     */
    public void overlay(HepRepInstance instance);

    /**
     * Adds an sub-instance to this instance.
     *
     * @param instance sub-instance.
     */
    public void addInstance(HepRepInstance instance);

    /**
     * Removes a sub-instance from this instance.
     *
     * @param instance sub-instance.
     */
    public void removeInstance(HepRepInstance instance);

    /**
     * Returns a collection of all sub-instances this instance keeps.
     *
     * @return collection of HepRepInstances.
     */
    public List/*<HepRepInstance>*/ getInstances();

    /**
     * Returns the associated type for this instance.
     *
     * @return associated HepRepType.
     */
    public HepRepType getType();

    /**
     * Adds a point to this instance.
     *
     * @param point to be added.
     */
    public void addPoint(HepRepPoint point);

    /**
     * Returns a collection of all points this instance keeps.
     *
     * @return collection of HepRepPoints.
     */
    public List/*<HepRepPoint>*/ getPoints();

    /**
     * Fills a double[3][n] array with the coordinates of all points, if
     * none of the points have any attributes defined on them.
     * The actual number of points filled is returned. In case the number
     * of points is larger than n, or if any points have attributes, -1 is returned.
     * One could then call getPoint().
     *
     * @see #getPoints()
     *
     * @return number of points filled in xyz, or -1 in case of error or non-implementation.
     *
     * ONLY in JAVA
     */

    int getPoints(double[][] xyz);
    /**
     * Returns true if this instance has a frame. Speedy access for iterator.
     *
     * ONLY in JAVA
     */

    boolean hasFrame();
    /**
     * Returns String layername. Speedy access for iterator.
     *
     * ONLY in JAVA
     */

    String getLayer();
    /**
     * Returns the parent of this instance.
     *
     * @return parent of instance, or null if top-level.
     */
    public HepRepInstance getSuperInstance();

    /**
     * Returns a deep copy of this instance.
     *
     * @param typeTree needed to find the associated type.
     * @param parent to which the copy is added.
     * @return copy of this instance.
     * @throws CloneNotSupportedException if copying is not possible.
     */
    public HepRepInstance copy(HepRepTypeTree typeTree, HepRepInstance parent) throws CloneNotSupportedException;
    /**
     * Returns a deep copy of this instance.
     *
     * @param typeTree needed to find the associated type.
     * @param parent to which the copy is added.
     * @param filter run on all instances before copying.
     * @return copy of this instance.
     * @throws CloneNotSupportedException if copying is not possible.
     */
    public HepRepInstance copy(HepRepTypeTree typeTree, HepRepInstance parent, HepRepSelectFilter filter) throws CloneNotSupportedException;

    /**
     * Returns a deep copy of this instance.
     *
     * @param typeTree needed to find the associated type.
     * @param parent to which the copy is added.
     * @return copy of this instance.
     * @throws CloneNotSupportedException if copying is not possible.
     */
    public HepRepInstance copy(HepRepTypeTree typeTree, HepRepInstanceTree parent) throws CloneNotSupportedException;
    /**
     * Returns a deep copy of this instance.
     *
     * @param typeTree needed to find the associated type.
     * @param parent to which the copy is added.
     * @param filter run on all instances before copying.
     * @return copy of this instance.
     * @throws CloneNotSupportedException if copying is not possible.
     */
    public HepRepInstance copy(HepRepTypeTree typeTree, HepRepInstanceTree parent, HepRepSelectFilter filter) throws CloneNotSupportedException;


    /**
     * Sets a User Object on this instance.
     *
     * @param object User Object.
     */
    public void setUserObject(Object object);

    /**
     * Returns a user object previously set on this instance.
     *
     * @return User Object.
     */
    public Object getUserObject();
} // class or interface