/*
 *                 Sun Public License Notice
 * 
 * The contents of this file are subject to the Sun Public License
 * Version 1.0 (the "License"). You may not use this file except in
 * compliance with the License. A copy of the License is available at
 * http://www.sun.com/
 * 
 * The Original Code is NetBeans. The Initial Developer of the Original
 * Code is Sun Microsystems, Inc. Portions Copyright 1997-2003 Sun
 * Microsystems, Inc. All Rights Reserved.
 */

package org.netbeans.api.web.dd.common;
/**
 * Parent of all DD API interfaces.
 *
 *
Important note: Do not provide an implementation of this interface unless you are a DD API provider!
 *
 *
 * @author Milan Kuchtiak
 */
public interface CommonDDBean {
    /**
     * Adds property change listener to particular CommonDDBean object (WebApp object).
     * @param pcl property change listener
     */
    public void addPropertyChangeListener(java.beans.PropertyChangeListener pcl);
    /**
     * Removes property change listener from CommonDDBean object.
     * @param pcl property change listener
     */
    public void removePropertyChangeListener(java.beans.PropertyChangeListener pcl);
    /**
     * Sets the id attribute for related dd element. E.g.
<servlet id="xyz">
  ...
</servlet>
     *
     *
     * @param value the value for id attribute
     */    
    public void setId(java.lang.String value);
    /**
     * Returns the id attribute for related dd element.
In most cases the id attribute is not specified.
     * @return value of id attribute or null if not specified
     */   
    public java.lang.String getId();
    /**
     * Returns the clonned CommonDDBean object.
     * @return the clonned (not bound to bean graph) CommonDDBean object
     */       
    public Object clone();
    /**
     * Returns the CommonDDBean object or array of CommonDDBean object for given property.

     * E.g. for retrieving the servlet-class value on Servlet object he getValue("ServletClass"); can be used.
     * @param propertyName name of the property the value is looking for
     * @return the bean/array of beans related to given property
     */      
    public Object getValue(String propertyName);
    /**
     * Writes the whole DD or its fraction (element related to CommonDDBean) to output stream.

     * For DD root object there is more convenient to use the {@link org.netbeans.api.web.dd.common.RootInterface#write} method.

     * The correct usage with file objects is :
WebApp webApp;
FileObject fo;
...
//  code that initializes and modifies the webApp object
...
FileLock lock;
try {
    lock=fo.lock();
} catch (FileAlreadyLockedException e) {
    // handling the exception
}
if (lock!=null) {
    try {
        OutputStream os=fo.getOutputStream(lock);
        try {
            webApp.write(os);
        } finally {
            os.close();
        }
    } finally {
        lock.releaseLock();
    }
}
...
     *
     * @param os output stream for writing
     */  
    public void write(java.io.OutputStream os) throws java.io.IOException;

}