net.sf.mmm.util.pojo.descriptor.api
Interface PojoDescriptor<POJO>

Type Parameters:

POJO - is the templated type of the pojo.

All Superinterfaces:

PojoAttributeType<POJO>

All Known Implementing Classes:

AbstractPojoDescriptor, PojoDescriptorImpl

public interface PojoDescriptor<POJO>
extends PojoAttributeType<POJO>

This interface describes the properties of a Pojo. A Pojo in this manner is more or less any java object.
This interface is an alternative to BeanInfo.
Look at the following example:

 public interface Pojo {
   Integer getFooBar();
   void setFooBar(int s);
   
   boolean hasSomeFlag();
   void setSomeFlag(Boolean flag);
   
   boolean isCool();
   void setCool();
   
   List<String> getColors();
   void addColor(String color);
   void removeColor(String color);
 }
 

This interface does NOT completely follow the JAVA-Beans specification. The properties "fooBar" and "someFlag" do NOT have the same type for reading and writing. Therefore the Introspector for java-beans or commons-beanutils can NOT be used to read and write these properties. Using this utility the properties can be accessed as described in the following table:

Name	Mode	Property-Type	Method	Note
fooBar	get	Integer	getFooBar()	-
fooBar	set	int	setFooBar(int)	-
someFlag	get	boolean	hasSomeFlag()	-
someFlag	set	Boolean	setSomeFlag(Boolean)	-
cool	get	boolean	isCool()	-
colors	get	List<String>	getColors()	-
color	add	String	addColor(String)	-
color	remove	String	removeColor(String)	-
colors	add	String	addColor(String)	enhanced copy
colors	remove	String	removeColor(String)	enhanced copy
colors	indexed-set	String	getColors().set(int, String)	enhanced virtual accessor

ATTENTION:
When using this interface without generic parameterization you can NOT properly call the getAccessor methods. If the type of your Pojo is unknown at compile-time, you need to parameterize with the unbound wildcard as PojoDescriptor<?>. In that case you can not call the get or set methods.

Since:

1.1.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

See Also:

PojoPropertyDescriptor

Method Summary

Object	addPropertyItem(POJO pojoInstance, String propertyName, Object item) This method adds the given item to the list-like property with the given propertyName from the given pojoInstance using the add accessor.
<ACCESSOR extends PojoPropertyAccessor> ACCESSOR	getAccessor(String property, PojoPropertyAccessorMode<ACCESSOR> mode) This method gets the accessor for the property with the given propertyName and for the given access mode.
<ACCESSOR extends PojoPropertyAccessor> ACCESSOR	getAccessor(String property, PojoPropertyAccessorMode<ACCESSOR> mode, boolean required) This method gets the accessor for the given mode from the descriptor with the given propertyName .
Object	getProperty(POJO pojoInstance, String property) This method gets the property identified by the given property from the given pojoInstance.
PojoPropertyDescriptor	getPropertyDescriptor(String propertyName) This method gets the descriptor for the property identified by the given propertyName.
Collection<? extends PojoPropertyDescriptor>	getPropertyDescriptors() This method gets the descriptors of all properties of the according pojo.
Object	getPropertyItem(POJO pojoInstance, String propertyName, int index) This method gets the item with the given index from the list-like property with the given propertyName of the given pojoInstance using the indexed getter accessor.
int	getPropertySize(POJO pojoInstance, String propertyName) This method gets the size of the property with the given propertyName from the given pojoInstance.
Boolean	removePropertyItem(POJO pojoInstance, String propertyName, Object item) This method removes the given item from an array or Collection using the remove property with the given propertyName from the given pojoInstance accessor.
Object	setProperty(POJO pojoInstance, String property, Object value) This method sets the given value for the property with the given property of the given pojoInstance.
Object	setPropertyItem(POJO pojoInstance, String propertyName, int index, Object item) This method sets the given item at the given index in the list-like property with the given propertyName of the given pojoInstance using the indexed setter accessor.

Methods inherited from interface net.sf.mmm.util.pojo.descriptor.api.attribute.PojoAttributeType

getPojoClass, getPojoType

Method Detail

getPropertyDescriptor

PojoPropertyDescriptor getPropertyDescriptor(String propertyName)

This method gets the descriptor for the property identified by the given propertyName.

Parameters:

propertyName - is the name of the requested property.

Returns:

the descriptor for the property identified by the given propertyName or null if no such property exists for the according pojo.

getPropertyDescriptors

Collection<? extends PojoPropertyDescriptor> getPropertyDescriptors()

This method gets the descriptors of all properties of the according pojo.

Returns:

a collection with all property descriptors

getAccessor

<ACCESSOR extends PojoPropertyAccessor> ACCESSOR getAccessor(String property,
                                                             PojoPropertyAccessorMode<ACCESSOR> mode)

This method gets the accessor for the property with the given propertyName and for the given access mode.

Type Parameters:

ACCESSOR - is the type of the requested accessor.

Parameters:

property - is the name of the property. If the given mode is GET it is treated as for getProperty(Object, String). If the given mode is SET it is treated as for setProperty(Object, String, Object).

mode - is the mode of the requested accessor.

Returns:

the requested accessor or null if NOT found (there is no property named propertyName, the property has no accessor for the given mode, etc.).

getAccessor

<ACCESSOR extends PojoPropertyAccessor> ACCESSOR getAccessor(String property,
                                                             PojoPropertyAccessorMode<ACCESSOR> mode,
                                                             boolean required)
                                                  throws PojoPropertyNotFoundException

This method gets the accessor for the given mode from the descriptor with the given propertyName .

Type Parameters:

ACCESSOR - is the type of the requested accessor.

Parameters:

property - is the name of the property. If the given mode is GET it is treated as for getProperty(Object, String). If the given mode is SET it is treated as for setProperty(Object, String, Object).

mode - is the mode of the requested accessor.

required - - if true the accessor is required and an exception is thrown if NOT found.

Returns:

the requested accessor or null if NOT found and required is false.

Throws:

PojoPropertyNotFoundException - if required is true and no property named propertyName was found or no accessor exists for that property with the given mode.

See Also:

getPropertyDescriptor(String), PojoPropertyDescriptor.getAccessor(PojoPropertyAccessorMode)

getProperty

Object getProperty(POJO pojoInstance,
                   String property)
                   throws PojoPropertyNotFoundException,
                          ReflectionException

This method gets the property identified by the given property from the given pojoInstance. The result depends on the form of the given property as shown by the following table:

property	accessor	example	equivalent
[a-zA-Z][a-zA-Z0-9]*	PojoPropertyAccessorNonArgMode.GET	fooBar	getFooBar()
[a-zA-Z][a-zA-Z0-9]* "[" [0-9]+ "]"	PojoPropertyAccessorIndexedNonArgMode.GET_INDEXED	fooBar[42]	getFooBar(42) getFooBar()[42] getFooBar().get(42)
[a-zA-Z][a-zA-Z0-9]* "['" [a-zA-Z0-9]+ "']"	PojoPropertyAccessorOneArgMode.GET_MAPPED	fooBar['key']	getFooBar("key") getFooBar().get("key")

Parameters:

pojoInstance - is the POJO instance where to access the property.

property - identifies the property to get as described above.

Returns:

the value of the requested property. It will be an instance of the type of the according getter. Depending on the POJO, the value may be null.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

setProperty

Object setProperty(POJO pojoInstance,
                   String property,
                   Object value)
                   throws PojoPropertyNotFoundException,
                          ReflectionException

This method sets the given value for the property with the given property of the given pojoInstance. The effect depends on the form of the given property as shown by the following table:

property	accessor	example	equivalent
[a-zA-Z][a-zA-Z0-9]*	PojoPropertyAccessorOneArgMode.SET	fooBar	setFooBar(value)
[a-zA-Z][a-zA-Z0-9]* "[" [0-9]+ "]"	PojoPropertyAccessorIndexedOneArgMode.SET_INDEXED	fooBar[42]	setFooBar(42, value) getFooBar()[42]=value getFooBar().set(42, value)
[a-zA-Z][a-zA-Z0-9]* "['" [a-zA-Z0-9]+ "']"	PojoPropertyAccessorTwoArgMode.SET_MAPPED	fooBar['key']	setFooBar("key", value) getFooBar().put("key", value)

Parameters:

pojoInstance - is the POJO instance where to access the property.

property - identifies the property to set as explained above.

value - is the property value to set. Depending on the POJO the value may be null.

Returns:

the result of the setter method. Will be null if the return type is void what should be the regular case.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

getPropertySize

int getPropertySize(POJO pojoInstance,
                    String propertyName)
                    throws PojoPropertyNotFoundException,
                           ReflectionException

This method gets the size of the property with the given propertyName from the given pojoInstance.

Parameters:

pojoInstance - is the POJO instance where to access the property.

propertyName - is the name of the property.

Returns:

the size of the requested property.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

addPropertyItem

Object addPropertyItem(POJO pojoInstance,
                       String propertyName,
                       Object item)
                       throws PojoPropertyNotFoundException,
                              ReflectionException

This method adds the given item to the list-like property with the given propertyName from the given pojoInstance using the add accessor.

Parameters:

pojoInstance - is the POJO instance where to access the property.

propertyName - is the name of the property.

item - is the item to add to the property.

Returns:

the result of the add-method. Will be null if the return type is void what should be the regular case.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

removePropertyItem

Boolean removePropertyItem(POJO pojoInstance,
                           String propertyName,
                           Object item)
                           throws PojoPropertyNotFoundException,
                                  ReflectionException

This method removes the given item from an array or Collection using the remove property with the given propertyName from the given pojoInstance accessor.

Parameters:

pojoInstance - is the POJO instance where to access the property.

propertyName - is the name of the property.

item - is the item to remove from the property.

Returns:

Boolean.TRUE if the item has been removed successfully and Boolean.FALSE if the item was NOT present in the array or Collection, or null if the accessor is pointing to a remove method that returns no boolean.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

getPropertyItem

Object getPropertyItem(POJO pojoInstance,
                       String propertyName,
                       int index)
                       throws PojoPropertyNotFoundException,
                              ReflectionException

This method gets the item with the given index from the list-like property with the given propertyName of the given pojoInstance using the indexed getter accessor.

Parameters:

pojoInstance - is the POJO instance where to add the given property item.

propertyName - is the name of the property.

index - is the position of the requested item (see List.get(int)).

Returns:

the result of the add-method. Will be null if the return type is void what should be the regular case.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.

setPropertyItem

Object setPropertyItem(POJO pojoInstance,
                       String propertyName,
                       int index,
                       Object item)
                       throws PojoPropertyNotFoundException,
                              ReflectionException

This method sets the given item at the given index in the list-like property with the given propertyName of the given pojoInstance using the indexed setter accessor.

Parameters:

pojoInstance - is the POJO instance where to access the property.

propertyName - is the name of the property.

index - is the position of the item to set (see List.set(int, Object)).

item - is the item to set at the given index.

Returns:

the result of the add-method. Will be null if the return type is void what should be the regular case.

Throws:

PojoPropertyNotFoundException - if the property with the given propertyName was NOT found or has no such accessor.

ReflectionException - if the underlying accessor caused an error during reflection.