Pax Reflector - Details

public interface ReflectorService
{
    :
    Object getObject( Object container, String member )
        throws ReflectionException;
    :
}

public class MyPojo
{
    private String m_Name;

    public MyPojo( String name )
    {
        m_Name = name;
    }

    public String getName()
    {
        return m_Name;
    }
}

// somewhere else
MyPojo pojo = new MyPojo( "Niclas" );
  :
String name = (String) reflector.getObject( pojo, "Name" );
 // name is now equal "Niclas".

String name = (String) reflector.getObject( "myroot.SomeMember.Another.MyPojo.Name" );

// is essentially the same as

String name = myroot.getSomeMember().getAnother().getMyPojo().getName();

private Def[] m_Abcs;

public Def getAbc( int index )
{
    return m_Abcs[ index ];
}

public void setAbc( int index, Def item )
{
    m_Abcs[ index ] = item;
}

// somewhere in initialization

reflector.addRootObject( "x", new WeakHashMap() );

// adding additional 'root objects'

public void addWeakRootObject( String name, Object obj )
{
    Map m = reflector.getMemberObject( "x" );
    m.put( name, obj );
}

package org.ops4j.pax.reflector;

/** The ReflectorService allows you to traverse object instances in a running application.
 * <p>
 * The ReflectorService operates with a cascaded dot-notation to identify object instances in
 * running memory. That means that by providing a name such as "abc.Def.Rst.Name" the equivalent
 * of (provided no special TypeHandlers kick in);
 * <pre>
 *  abc.getDef().getRst().getName()
 * </pre>
 * is called, if the JavaBeans-styled accessor methods are found. Also, public member fields will
 * also be looked for (higer priority) and accessed when possible.
 * </p>
 * <p>
 * Examples of syntaxes, and equivalents in direct Java code.
 * <table>
 * <tr><th>dot notation</th><th>Java</th><th>Comment</th></tr>
 * <tr><td>someRoot.Abc</td><td>someRoot.getAbc()</td><td></td></tr>
 * <tr><td>someRoot.Abc.Def</td><td>someRoot.getAbc().getDef()</td><td></td></tr>
 * <tr><td>someRoot.Abc['0']</td><td>someRoot.getAbc()[0]</td><td>If getAbc() returns an Array.</td></tr>
 * <tr><td>someRoot.Abc['0']</td><td>someRoot.getAbc().getAt(0)</td><td>If getAbc() returns a Collection</td></tr>
 * <tr><td>someRoot.Abc['Def']</td><td>someRoot.getAbc().get("Def")</td><td>If getAbc() returns a Map or Dictionary.</td></tr>
 * <tr><td>someRoot.Abc['0'].Rst</td><td>someRoot.getAbc().getAt(0).getRst()</td><td>If getAbc() returns a Collection</td></tr>
 * <tr><td>someRoot.Abc['Def'].Rst</td><td>someRoot.getAbc().get("Def").getRst()</td><td>If getAbc() returns a Map or Dictionary.</td></tr>
 * <tr><td><i>empty string</i></td><td></td><td>Only valid for getMemberNames() which will return all root object names.</td></tr>
 * </table>
 * </p>
 */
public interface ReflectorService
{
    /** Returns the human readable form of the object instance traversed from the objectname argument.
     * @param membername The name of the object of interested.
     *
     * @return The toString() value of the member value object.
     */
    String getMember( String membername )
        throws ReflectionException;

    /** Returns the object of the member by the given membername.
     *
     * @param membername The name of the object to traverse to and return.
     *
     * @return The object that is returned as the value of the member, either by getter, fields or special
     *         handling, such as the value of entries of Maps and Collections.
     */
    Object getMemberObject( String membername )
        throws ReflectionException;

    /** Returns the object of the member by the given membername, starting at the provided container.
     *
     * @param membername The name of the object to traverse to and return.
     *
     * @return The object that is returned as the value of the member, either by getter, fields or special
     *         handling, such as the value of entries of Maps and Collections.
     */
    Object getMemberObject( Object container, String memberName )
        throws ReflectionException;

    /** Assigns the value to the member identified by the membername argument.
     *
     * @param membername The name of the member to be assigned a value.
     * @param value The value to be assigned to the member. For primitives, the value is converted according to
     *              normal Java rules, but additionally a fully-qualified classname can be given, in which case
     *              the reflector will try to instantiate such class through the default constructor, and if
     *              successful assign the instance to the member.
     */
    void setMember( String membername, String value )
        throws ReflectionException;

    /** Assigns the value to the member identified by the membername argument.
     *
     * @param membername The name of the member to be assigned a value.
     * @param value The value to be assigned to the member.
     * @throws ReflectionException If the value is not assignable to the member type.
     */
    void setMemberObject( String membername, Object value )
        throws ReflectionException;

    /** Assigns the value to the member identified by the membername starting at the
     *  container object.
     *
     * @param membername The name of the member to be assigned a value.
     * @param value The value to be assigned to the member.
     * @throws ReflectionException If the value is not assignable to the member type.
     */
    void setMemberObject( Object container, String memberName, Object object )
        throws ReflectionException;

    /** Returns all the membernames found in the member identified by membername argument.
     * <p>
     * If the membername is an empty string, all root object names are returned.
     * </p>
     * @param membername The name of the member to query for <b>its</b> members.
     *
     * @throws ReflectionException If the member identified by the membername does not exist.
     */
    String[] getMemberNames( String membername )
        throws ReflectionException;

    /** Returns all the membernames found in the object.
     *
     * @param object The Java instance to query for its members.
     *
     * @throws ReflectionException
     */
    String[] getMemberNames( Object object )
        throws ReflectionException;

    /** Returns the Class of the member identified by the membername argument.
     *
     * @param membername The name of the member to query for its Class.
     */
    Class getMemberClass( String membername )
        throws ReflectionException;

    /** Returns the Class of the member identified by the membername in the provided
     *  container.
     *
     * @param membername The name of the member of the container to query for its Class.
     */
    Class getMemberClass( Object container, String memberName )
        throws ReflectionException;

    /** Returns the name of the Class of the member identified by the membername argument.
     *
     * @param membername The name of the member to query for its Class.
     */
    String getMemberClassName( String membername )
        throws ReflectionException;

    /** Returns the name of the Class of the member identified by the membername in the provided
     *  container.
     *
     * @param membername The name of the member of the container to query for its Class.
     */
    String getMemberClassName( Object container, String memberName )
        throws ReflectionException;

    /** Checks with the member of the given membername can be set to a value.
     * @param membername The member to be tested if it can be set by a setMemberObject() method call.
     */
    boolean isMemberSettable( String membername )
        throws ReflectionException;

    /** Checks with the member of the given membername can be set to a value.
     * @param container The container from where we should test if a member can be set to a value, by calling the
     *                  setMemberObject() method.
     * @param membername The member in the provided container to be tested if it can be set by a setMemberObject()
     *                   method call.
     */
    boolean isMemberSettable( Object container, String membername )
        throws ReflectionException;

    /** Returns the container part of the membername.
     * <p>
     * This method must correctly return the container part of the full membername. For instance;
     * getContainerPart( "someRoot.Abc.Def" ), must return "someRoot.Abc",
     * getContainerPart( "someRoot.Abc['Def']" ), must return "someRoot.Abc", and
     * getContainerPart( "someRoot.Abc['Def'].Rst" ), must return "someRoot.Abc['Def']".
     * </p>
     * @param membername The membername to be worked upon.
     */
    String extractContainerPart( String membername )
        throws ReflectionException;

    /** Returns the Name part of the membername.
     * <p>
     * This method must correctly return the Name part of the full membername. For instance;
     * getContainerPart( "someRoot.Abc.Def" ), must return "Def",
     * getContainerPart( "someRoot.Abc['Def']" ), must return "['Def']", and
     * getContainerPart( "someRoot.Abc['Def'].Rst" ), must return "Rst".
     * </p>
     * @param membername The membername to be worked upon.
     */
    String extractNamePart( String membername )
        throws ReflectionException;

    /** Appends the name to the container name.
     *
     * @param container The actual container so that the type can be determined.
     * @param containerpart The name of the container.
     * @param namepart The name part to append to the containerpart.
     */
    String append( Object container, String containerpart, String namepart );

    /** Adds a <i>Root Object</i> to the Reflector instance.
     * <p>
     * The name must also be unique and no other root object may have been registered with the
     * same name.
     * </p>
     *
     * @param name The name of the <i>Root Object</i>. The name may only contain valid Java characters, as
     *             reported by Character.isJavaIdentifierPart(char ch).
     * @param object The object instance to be registered at the provided name.
     *
     * @throws IllegalArgumentException if the name is not valid, or if there has already been a root object
     *                                  registered with the same name previously.
     */
    void addRootObject( String name, Object object )
        throws IllegalArgumentException;

    /** Removes the root object with registered under the provided name.
     * <p>
     * Although this method removes the registration, the ReflectorService implementation must not keep
     * a strong reference to the registered object, so that if the registered object
     * has no other references, the registration will quitely be removed automatically.
     * </p>
     * <p>
     * If there is no root object registered under the provided name, this method will simply return.
     * </p>
     * @param name The name under which the root object was previously registered.
     */
    void removeRootObject( String name );
}

public class MyRoot
{
    private Friend m_myFriend;

    public Friend getMyFriend()
    {
        return m_myFriend;
    }
}

public class Friend
{
    public String name;
    public int    age;
}

// elsewhere....

String name = reflector.getMember( "someRoot.MyFriend.name" );

Friend friend = ....

String name = (String) reflector.getMemberObject( friend, "name" );

Friend friend = ....

reflector.setMemberObject( friend, "name", "Niclas" );

reflector.setMemberObject( friend, "age", "41" );

// or

reflector.setMemberObject( "someRoot.MyFriend.name", "Niclas" );

reflector.setMemberObject( "someRoot.MyFriend.age", "41" );

reflector.setMemberObject( "someRoot.MyFriend.age", new Integer(41) );

public class MyFunkyHandler
{
    public void doSomethingImportant( OurFunkyArgument argument )
    {
        // DO
    }
}

public interface OurFunkyArgument
{
    // getters according to JavaBeans model
}

public class MyFunkyHandler
{
    private List m_history = new ArrayList();
    private int m_maxHistory = 10;

    public void doSomethingImportant( OurFunkyArgument argument )
    {
        manageHistory( argument );
         // DO

    }
    private void manageHistory( OurFunkyArgument arg )
    {
        m_history.add( arg );
        while( m_history.size() > m_maxHistory )
        {
            m_history.remove(0);
        }
    }
}

private int m_maxSize = 0;

public int getHistorySize()
{
    return m_maxSize;
}

public void setHistorySize( int size )
{
    m_maxSize = size;
}