category.java

jConfig,JAVA读取XML的开源项目

package org.jconfig;

import java.util.Properties;

import org.jconfig.event.CategoryChangedEvent;
import org.jconfig.event.CategoryListener;
import org.jconfig.event.PropertyChangedEvent;
import org.jconfig.event.PropertyListener;

/**
 * This class is the result of countless discussions of what
 * a Category should be. After determing that it should be
 * another class, and that we can do something useful, we
 * created this Category.
 *
 * A Category is a logical extension of the Configuration
 * has Categories has Properties has Value frame-of-mind.
 * The primary goal is to reduce redundancy in source code
 * when using setter and getters that include Category
 * information.
 *
 * @since 2.2
 * @author Andreas Mecky <[e-mail]>
 * @author Terry Dye <[e-mail]>
 */
public interface Category {
    
    /**
     * Sets the property with the value given. This will override any
     * existing property values if the property name is duplicated.
     * This will create a new property if no property exists.
     *
     * Setting the value to &lt;null&gt; will remove the property
     * from the Category;
     *
     * @since 2.2
     * @param propertyName
     * @param propertyValue
     * @return
     */
    public Category setProperty(String propertyName, String propertyValue);
    
    /**
     * Searches for the property with the specified key in this property list.
     * If the key is not found in this property list, the default property list,
     * and its defaults, recursively, are then checked. The method returns
     * <code>null</code> if the property is not found.
     *
     * @since 2.2
     * @param   propertyName the property key.
     * @return  the value in this property list with the specified key value.
     */
    public String getProperty(String propertyName);
    /**
     * Searches for the property with the specified key in this property list.
     * If the key is not found in this property list, the default property list,
     * and its defaults, recursively, are then checked. The method returns the
     * default value argument if the property is not found.
     *
     * @since 2.2
     * @param   propertyName The property name.
     * @param   defaultValue The default value.
     * @return  the value in this property list with the specified key value or
     * the defaultValue.
     */
    public String getProperty(String propertyName, String defaultValue);
    
    /**
     * Returns the name of this category.
     *
     * @since 2.2
     * @return The name of the category.
     */
    public String getCategoryName();
    /**
     * Adds the specified category listener to receive category
     * changed events from this category.
     *
     * @since 2.2
     * @param listener The ConfigurationListener
     */
    public void addCategoryListener(CategoryListener listener);
    /**
     * Removes the specified category listener from the category
     * change events from this category.
     *
     * @since 2.2
     * @param listener The ConfigurationListener
     */
    public void removeCategoryListener(CategoryListener listener);
    /**
     * Deliver category changed event to all listeners that are registered
     * with our listener list.
     *
     * @since 2.2
     * @param event The ConfigurationChangedEvent
     */
    public void fireCategoryChangedEvent(CategoryChangedEvent event);
    /**
     * Return all properties related to this category
     *
     * @since 2.2
     * @return The Properties
     */
    public Properties getProperties();
    
    public String[] getArray(String key);
    
    public String[] getArray(String key, String[] defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name The name of the property
     * @param defaultValue The default value
     * @return If the String value can be converted to Boolean, the
     * value will be return, otherwise the the default value.
     */
    public boolean getBooleanProperty(String name, boolean defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name
     * @param value
     */
    public void setBooleanProperty(String name, boolean value);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name The name of the property
     * @param defaultValue The default value
     * @return If the String value can be converted to Boolean, the
     * value will be return, otherwise the the default value.
     */
    public char getCharProperty(String name, char defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param key
     * @param value
     */
    public void setCharProperty(String key, char value);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name The name of the property
     * @param defaultValue The default value
     * @return If the String value can be converted to Boolean, the
     * value will be return, otherwise the the default value.
     */
    public double getDoubleProperty(String name, double defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name The name of the property
     * @param defaultValue The default value
     * @return If the String value can be converted to Boolean, the
     * value will be return, otherwise the the default value.
     */
    public int getIntProperty(String name, int defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param key
     * @param value
     */
    public void setIntProperty(String key, int value);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param name The name of the property
     * @param defaultValue The default value
     * @return If the String value can be converted to Boolean, the
     * value will be return, otherwise the the default value.
     */
    public long getLongProperty(String name, long defaultValue);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param key
     * @param value
     */
    public void setLongProperty(String key, long value);
    
    /**
     * Getter for property configurationName.
     *
     * @since 2.2
     * @return Value of property configurationName.
     *
     */
    public String getConfigurationName();
    
    /**
     * Setter for property configurationName.
     *
     * @since 2.2
     * @param configurationName New value of property configurationName.
     *
     */
    public void setConfigurationName(String configurationName);
    
    /**
     * Helper method to allow for strong-binding within Properties.
     *
     * @since 2.2
     * @param key
     * @param value
     */
    public void setDoubleProperty(String key, double value);
    
    /**
     * Adds the given listener to the list that wish to receive the
     * {@link org.jconfig.event.PropertyChangedEvent PropertyChangedEvent}.
     *
     * @since 2.2
     * @param listener
     */
    public void addPropertyListener( PropertyListener listener );
    
    /**
     * Removes the given listener to the list that wish to receive the
     * {@link org.jconfig.event.PropertyChangedEvent PropertyChangedEvent}.
     *
     * @since 2.2
     * @param listener
     */
    public void removePropertyListener( PropertyListener listener );
    
    /**
     * Notifies all {@link PropertyListener PropertyListeners} of changes
     * to the property (added, removed, changed).
     *
     * @param event 
     */
    public void firePropertyChangedEvent( PropertyChangedEvent event );
    
    /**
     *
     * @param extendsCategory
     */
    public void setExtendsCategory(String extendsCategory);
    
    /**
     *
     * @return
     */
    public String getExtendsCategory();
    
    /**
     * This method will change the name of the category.
     * 
     * @param name the new name of the category
     */
    public void renameCategory(String name);
        
}