org.apache.commons.beanutils.LazyDynaClass Maven / Gradle / Ivy
Show all versions of commons-beanutils Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.apache.commons.beanutils;
/**
* DynaClass which implements the MutableDynaClass interface.
*
* A MutableDynaClass is a specialized extension to DynaClass
* that allows properties to be added or removed dynamically.
*
* This implementation has one slightly unusual default behaviour - calling
* the getDynaProperty(name) method for a property which doesn't
* exist returns a DynaProperty rather than null. The
* reason for this is that BeanUtils calls this method to check if
* a property exists before trying to set the value. This would defeat the object
* of the LazyDynaBean which automatically adds missing properties
* when any of its set() methods are called. For this reason the
* isDynaProperty(name) method has been added to this implementation
* in order to determine if a property actually exists. If the more normal
* behaviour of returning null is required, then this can be achieved
* by calling the setReturnNull(true).
*
* The add(name, type, readable, writable) method is not implemented
* and always throws an UnsupportedOperationException. I believe
* this attributes need to be added to the DynaProperty class
* in order to control read/write facilities.
*
* @see LazyDynaBean
* @author Niall Pemberton
*/
public class LazyDynaClass extends BasicDynaClass implements MutableDynaClass {
/**
* Controls whether changes to this DynaClass's properties are allowed.
*/
protected boolean restricted;
/**
* Controls whether the getDynaProperty() method returns
* null if a property doesn't exist - or creates a new one.
*
* Default is false.
*/
protected boolean returnNull = false;
/**
* Construct a new LazyDynaClass with default parameters.
*/
public LazyDynaClass() {
this(null, (DynaProperty[])null);
}
/**
* Construct a new LazyDynaClass with the specified name.
*
* @param name Name of this DynaBean class
*/
public LazyDynaClass(String name) {
this(name, (DynaProperty[])null);
}
/**
* Construct a new LazyDynaClass with the specified name and DynaBean class.
*
* @param name Name of this DynaBean class
* @param dynaBeanClass The implementation class for new instances
*/
public LazyDynaClass(String name, Class dynaBeanClass) {
this(name, dynaBeanClass, null);
}
/**
* Construct a new LazyDynaClass with the specified name and properties.
*
* @param name Name of this DynaBean class
* @param properties Property descriptors for the supported properties
*/
public LazyDynaClass(String name, DynaProperty[] properties) {
this(name, LazyDynaBean.class, properties);
}
/**
* Construct a new LazyDynaClass with the specified name, DynaBean class and properties.
*
* @param name Name of this DynaBean class
* @param dynaBeanClass The implementation class for new intances
* @param properties Property descriptors for the supported properties
*/
public LazyDynaClass(String name, Class dynaBeanClass, DynaProperty properties[]) {
super(name, dynaBeanClass, properties);
}
/**
*
Is this DynaClass currently restricted.
* If restricted, no changes to the existing registration of
* property names, data types, readability, or writeability are allowed.
* @return true if this {@link MutableDynaClass} cannot be changed
* otherwise false
*/
public boolean isRestricted() {
return restricted;
}
/**
* Set whether this DynaClass is currently restricted.
* If restricted, no changes to the existing registration of
* property names, data types, readability, or writeability are allowed.
* @param restricted true if this {@link MutableDynaClass} cannot
* be changed otherwise false
*/
public void setRestricted(boolean restricted) {
this.restricted = restricted;
}
/**
* Should this DynaClass return a null from
* the getDynaProperty(name) method if the property
* doesn't exist.
*
* @return true if a null {@link DynaProperty}
* should be returned if the property doesn't exist, otherwise
* false if a new {@link DynaProperty} should be created.
*/
public boolean isReturnNull() {
return returnNull;
}
/**
* Set whether this DynaClass should return a null from
* the getDynaProperty(name) method if the property
* doesn't exist.
* @param returnNull true if a null {@link DynaProperty}
* should be returned if the property doesn't exist, otherwise
* false if a new {@link DynaProperty} should be created.
*/
public void setReturnNull(boolean returnNull) {
this.returnNull = returnNull;
}
/**
* Add a new dynamic property with no restrictions on data type,
* readability, or writeability.
*
* @param name Name of the new dynamic property
*
* @exception IllegalArgumentException if name is null
* @exception IllegalStateException if this DynaClass is currently
* restricted, so no new properties can be added
*/
public void add(String name) {
add(new DynaProperty(name));
}
/**
* Add a new dynamic property with the specified data type, but with
* no restrictions on readability or writeability.
*
* @param name Name of the new dynamic property
* @param type Data type of the new dynamic property (null for no
* restrictions)
*
* @exception IllegalArgumentException if name is null
* @exception IllegalStateException if this DynaClass is currently
* restricted, so no new properties can be added
*/
public void add(String name, Class type) {
if (type == null) {
add(name);
} else {
add(new DynaProperty(name, type));
}
}
/**
* Add a new dynamic property with the specified data type, readability,
* and writeability.
*
* N.B.Support for readable/writeable properties has not been implemented
* and this method always throws a UnsupportedOperationException.
*
* I'm not sure the intention of the original authors for this method, but it seems to
* me that readable/writable should be attributes of the DynaProperty class
* (which they are not) and is the reason this method has not been implemented.
*
* @param name Name of the new dynamic property
* @param type Data type of the new dynamic property (null for no
* restrictions)
* @param readable Set to true if this property value
* should be readable
* @param writeable Set to true if this property value
* should be writeable
*
* @exception UnsupportedOperationException anytime this method is called
*/
public void add(String name, Class type, boolean readable, boolean writeable) {
throw new java.lang.UnsupportedOperationException("readable/writable properties not supported");
}
/**
* Add a new dynamic property.
*
* @param property Property the new dynamic property to add.
*
* @exception IllegalArgumentException if name is null
* @exception IllegalStateException if this DynaClass is currently
* restricted, so no new properties can be added
*/
protected void add(DynaProperty property) {
if (property.getName() == null) {
throw new IllegalArgumentException("Property name is missing.");
}
if (isRestricted()) {
throw new IllegalStateException("DynaClass is currently restricted. No new properties can be added.");
}
// Check if property already exists
if (propertiesMap.get(property.getName()) != null) {
return;
}
// Create a new property array with the specified property
DynaProperty[] oldProperties = getDynaProperties();
DynaProperty[] newProperties = new DynaProperty[oldProperties.length+1];
System.arraycopy(oldProperties, 0, newProperties, 0, oldProperties.length);
newProperties[oldProperties.length] = property;
// Update the properties
setProperties(newProperties);
}
/**
* Remove the specified dynamic property, and any associated data type,
* readability, and writeability, from this dynamic class.
* NOTE - This does NOT cause any
* corresponding property values to be removed from DynaBean instances
* associated with this DynaClass.
*
* @param name Name of the dynamic property to remove
*
* @exception IllegalArgumentException if name is null
* @exception IllegalStateException if this DynaClass is currently
* restricted, so no properties can be removed
*/
public void remove(String name) {
if (name == null) {
throw new IllegalArgumentException("Property name is missing.");
}
if (isRestricted()) {
throw new IllegalStateException("DynaClass is currently restricted. No properties can be removed.");
}
// Ignore if property doesn't exist
if (propertiesMap.get(name) == null) {
return;
}
// Create a new property array of without the specified property
DynaProperty[] oldProperties = getDynaProperties();
DynaProperty[] newProperties = new DynaProperty[oldProperties.length-1];
int j = 0;
for (int i = 0; i < oldProperties.length; i++) {
if (!(name.equals(oldProperties[i].getName()))) {
newProperties[j] = oldProperties[i];
j++;
}
}
// Update the properties
setProperties(newProperties);
}
/**
* Return a property descriptor for the specified property.
*
* If the property is not found and the returnNull indicator is
* true, this method always returns null.
*
* If the property is not found and the returnNull indicator is
* false a new property descriptor is created and returned (although
* its not actually added to the DynaClass's properties). This is the default
* beahviour.
*
* The reason for not returning a null property descriptor is that
* BeanUtils uses this method to check if a property exists
* before trying to set it - since these Lazy implementations automatically
* add any new properties when they are set, returning null from
* this method would defeat their purpose.
*
* @param name Name of the dynamic property for which a descriptor
* is requested
* @return The dyna property for the specified name
*
* @exception IllegalArgumentException if no property name is specified
*/
public DynaProperty getDynaProperty(String name) {
if (name == null) {
throw new IllegalArgumentException("Property name is missing.");
}
DynaProperty dynaProperty = (DynaProperty)propertiesMap.get(name);
// If it doesn't exist and returnNull is false
// create a new DynaProperty
if (dynaProperty == null && !isReturnNull() && !isRestricted()) {
dynaProperty = new DynaProperty(name);
}
return dynaProperty;
}
/**
* Indicate whether a property actually exists.
*
* N.B. Using getDynaProperty(name) == null
* doesn't work in this implementation because that method might
* return a DynaProperty if it doesn't exist (depending on the
* returnNull indicator).
*
* @param name The name of the property to check
* @return true if there is a property of the
* specified name, otherwise false
* @exception IllegalArgumentException if no property name is specified
*/
public boolean isDynaProperty(String name) {
if (name == null) {
throw new IllegalArgumentException("Property name is missing.");
}
return propertiesMap.get(name) == null ? false : true;
}
}