oracle.adfmf.framework.api

Class GenericTypeBeanSerializationHelper

Object

oracle.adfmf.framework.api.GenericTypeBeanSerializationHelper

public class GenericTypeBeanSerializationHelper
extends Object

GenericTypeBeanSerializationHelper is a helper class to provide an easy way for application developers to convert between ADFMF internal GenericType objects and their user defined POJOs. Currently the only place GenericType objects are exposed are for SOAP Data Controls.

The following rules are used by GenericTypeBeanSerializationHelper to perform the conversion to and from GenericType objects:

POJO to GenericType:

• Standard Java bean reflection rules are used for determining properties.
• Transient properties are ignored in the conversion process.
• Readable properties will be converted into a GenericType attribute.
• Array properties are represented as repeated attributes in the GenericType.
• Map properties are represented as individual attributes in the GenericType.
• Non-primitive properties will be represented as nested GenericTypes objects.

GenericType to POJO:

• Standard Java bean reflection rules are used for determining properties.
• Transient properties are ignored in the conversion process.
• Writable properties will be converted from GenericType attributes.
• Repeated attributes in the GenericType will be converted into an array object
• If the POJO implements the Map interface then any properties that can not be set via standard accessors will set in the POJO via the Map set method.
• Non-primitive attributes will be represented as nested POJO objects.

Example: Suppose we have a web service that passes back and forth an Employee element with the following properties:

• name of type String
• address a complex object with street, city, state, and zipcode attributes
• id of type long
• salary of type float
• phones of type String and could repeat

While this type is fairly simple, it is not very convenient to work with as a GenericType. Java developers tend to like have stronger typed objects to use in their code. For sake of argument, lets also say the developer would like to reuse the Employee object throughout their business logic that might also contain an additional property password that should never be transmitted to the back-end web service. Given that, their Employee object could look something like this:

 public class Employee {
        public String   getName()                    { return name;              }
        public void     setName(String name)         { this.name = name;         }
        
        public Address  getAddress()                 { return address;           }
        public void     setAddress(Address address)  { this.address = address;   }
        
        public long     getId()                      { return id;                }
        public void     setId(long id)               { this.id = id;             }
        
        public float    getSalary()                  { return salary;            }
        public void     setSalary(float salary)      { this.salary = salary;     }
        
        public String   getPassword()                { return password;          }
        public void     setPassword(String password) { this.password = password; }
        
        public String[] getPhone()                   { return phone;             }
        public void     setPhone(String phone)       { this.phone = phone;       }
 
        protected           String   name;
        protected           Address  address;
        protected           long     id;
        protected           float    salary;
        protected           String[] phone;
        protected transient String   password;
 }
 

 public class Address {
        public String  getStreet()                  { return street;            }
        public void    setStreet(String street)     { this.street = street;     }
        
        public String  getCity()                    { return city;              }
        public void    setCity(String city)         { this.city = city;         }
        
        public String  getState()                   { return state;             }
        public void    setState(String state)       { this.state = state;       }
 
        public String  getZipcode()                 { return zipcode;           }
        public void    setZipcode(String state)     { this.zipcode = zipcode;   }
 
        protected           String  street;
        protected           String  city;
        protected           String  state;
        protected           String  zipcode;
 }
 

Conversion Notes:

1. password is defined as transient so by the conversion rules above, this property is ignored with respect to the conversion algorithm.
2. name, address, id, and salary will all be converted to and from the GenericType since they have both getter and setter accessors.
3. based on the type of the property, properties can be coerced between types, with well known standard type coercing rules defined in oracle.adfmf.misc.Converter#coerceToType(Object,Class)
4. complex objects (like address) that do not have well known coercing rules will simply be recursed by the conversion algorithm to either build the child GenericType or to create and populate the POJO complex object depending on the direction of the conversion.
5. phone is an array of strings each representing a unique phone number. Since the cardinality of this element is greater than one, the conversion algorithm will find all matches of the phone attribute in the GenericType object and make them into an array and invoke setPhone on the bean. And for the toGenericType conversion will simply take each array element and append it to the toGenericType as an individual phone attribute.

Using the following classes:

    final String EMPLOYEE_VIRTUAL_BEAN_NAME = "EmployeeDC.Types.Employee";
    Employee     emp                        = getEmployee();
    GenericType  gt                         = null;
    
    gt  = GenericTypeBeanSerializationHelper.toGenericType(EMPLOYEE_VIRTUAL_BEAN_NAME, emp);
    
    or
    
    emp = GenericTypeBeanSerializationHelper.fromGenericType(Employee.class, gt, null);
    
    Sometimes, it is useful to send in a reference to an existing instance to 
    allow the methods to fill that instead of it always returning a new instance. For example,
    
    Employee emp = new Employee();
    
    GenericTypeBeanSerializationHelper.fromGenericType(emp, gt, null);
    
    This allows to have a 'reusable' object that to be deserialized to to over and over again.
    To populate an existing bean instance use the Object version otherwise use the class version.
    
 

Best Practices

• Typically java bean objects (POJOs) follow their associated GenericType structure fairly closely.
• When deviating from the GenericType structure, one of the following strategies are done:
  1. Additional bean properties are declared transient
  2. Optional properties can be excluded from the POJO provided the backing service can handle the missing data if used as an operation parameter.
• Currently the only place GenericType objects are exposed are for SOAP Data Controls. These virtual types have an associated virtual bean name that will be passed into the toGenericType method. The virtual bean name can be obtained by hovering over the virtual type in the Data Controls window of JDeveloper. This is typically in the format <DCName>.Types.<methodName>.<argName>.

See Also:

GenericType, Converter.coerceToType(Object,Class)

Method Summary

Methods

Modifier and Type	Method and Description
static Object	fromGenericType(Class beanClass, GenericType gt) Method used to deserialize the passed-in GenericType to Java Bean object.
static Object	fromGenericType(Class beanClass, GenericType gt, String attributeName) This method is used to deserialize the passed-in GenericType into a POJO.
static void	fromGenericType(Object beanInstance, GenericType gt) Method used to deserialize the passed-in GenericType to an existing Java Bean instance.
static GenericType	toGenericType(String virtualBeanName, Object bean) Method used to serialize the passed in Java object to a GenericType.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

toGenericType

public static GenericType toGenericType(String virtualBeanName,
                        Object bean)

Method used to serialize the passed in Java object to a GenericType. Typical usage is the java developer wants to invoke a web service operation from their application business logic. In this case we need to create the input parameters to pass to the web service operation. To do this we:

1. create a class that mimics the structure of the argument types (i.e. like Employee in the above example). This class (POJO) should declare properties for any fields in <methodName>_parameters.<argName> that you wish to populate.
2. determine the name of the virtualBeanName by hovering over the argument name you wish to create, and take note of the value that pops up. This is typically in the format <DCName>.Types.<methodName>.<argName>.
3. determine the programmatic sources for each of the properties and utilizing the POJOs setter methods populate the object
4. convert the POJO into the GenericType using the toGenericType method.

Parameters:

virtualBeanName - the name of the Data Control type to convert to

bean - Object to be serialized

Returns:

GenericType

fromGenericType

public static void fromGenericType(Object beanInstance,
                   GenericType gt)

Method used to deserialize the passed-in GenericType to an existing Java Bean instance. For example, this can be used to deserialize a web service generic type object into an existing bean data control's provider. This allows to have a 'reusable' object that we can deserialize to over and over again.

Parameters:

beanInstance - instance of the Java Bean to populate

gt - GenericType to deserialize

See Also:

AdfmfJavaUtilities.getDataControlProvider(java.lang.String)

fromGenericType

public static Object fromGenericType(Class beanClass,
                     GenericType gt)

Method used to deserialize the passed-in GenericType to Java Bean object.

The beanClass argument (and any other class referenced as nested properties) must have a public default constructor defined, or class creation will fail. beanClass and nested properties must not be an interface or abstract class either unless they are of type java.util.List or java.util.Map. In that case, this method will instantiate an ArrayList or HashMap, respectively.

This is the same as calling fromGenericType(Class beanClass, GenericType gt, String attributeName) with null for attributeName.

Parameters:

beanClass - Class of the Java Bean to create

gt - GenericType to deserialize

Returns:

Java Object for the corresponding Class passed in.

fromGenericType

public static Object fromGenericType(Class beanClass,
                     GenericType gt,
                     String attributeName)

This method is used to deserialize the passed-in GenericType into a POJO.

The beanClass argument (and any other class referenced as nested properties) must have a public default constructor defined, or class creation will fail. beanClass and nested properties must not be an interface or abstract class either unless they are of type java.util.List or java.util.Map. In that case, this method will instantiate an ArrayList or HashMap, respectively.

Typical usage is to create a class that mimics the structure of the return type attempting to be deserialized.

For example, to determine the structure of the returned value for a SOAP DC, go to the Data Controls window and find the structure <methodName>.Return. This is always the GenericType instance returned from web service calls.

Your bean class should declare properties for any fields in <methodName>.Return that you wish to populate.

If the method call returns an array, you will need to use the attributeName parameter. If <methodName>.Return.return is the array you wish to deserialize and is of type int[], then the call would be:
fromGenericType(int[].class, gt, "return");

Parameters:

beanClass - Class of the Java Bean to create

gt - GenericType to deserialize

attributeName - the name of the attribute on the passed in GenericType that corresponds to the class to create

Returns:

Java Object for the corresponding Class passed in.