org.inxar.hotswap
Interface Proxy


public interface Proxy

A Proxy contains a reference to an Object whose implementation may change during the life of an application; when the change is detected, the underlying sourcefile is recompiled, the class is reloaded, and a new object is instantiated. Proxy also acts a container for object constructor arguments that, if non-null, will be used when reflecting new object instances.

To use this library effectively, one must be mindful not to hold direct references to the object instance that the Proxy contains (returned by the Proxy.get() method). Rather, keep the Proxy around instead and retrieve the object as necessary to ensure that the implementation is always current.

If the parent ProxyClass of this Proxy was instantiated as a JDK1.3 dynamic proxy class, this Proxy instance will also implement the interfaces of that Class. In that case the implementation of the Proxy method signatures can potentially collide with user interface method signatures; hence, all the methods in this interface carry a hotswap prefix. End-users should avoid naming their methods with this prefix.

Since:
0.8.2

Method Summary
 void hotswap_addObjectSwapListener(ProxyEventListener l)
          Adds the given listener of ProxyObjectSwapEvent notifications.
 void hotswap_dequeue()
          Explicitly dequeues this Proxy as a participant in the next hotswap transaction in the parent ProxyClass.
 void hotswap_enqueue()
          Explicitly enqueues this Proxy as a participant in the next hotswap transaction in the parent ProxyClass.
 Object[] hotswap_getConstructorArguments()
          Returns the object constructor arguments or null if none have been specified.
 Class[] hotswap_getConstructorParameters()
          Returns the object constructor parameters or null if none have been specified.
 Object hotswap_getInstance()
          Returns the contained Object without trying to hotswap.
 ProxyClass hotswap_getProxyClass()
          Returns the parent ProxyClass.
 int hotswap_getStatus()
          Equivalent to hotswap_getProxyClass().getStatus().
 boolean hotswap_isEnqueued()
          Returns true if this Proxy instance is registered as a participant in the next hotswap transaction.
 void hotswap_release()
          Explicitly releases any resources associated with this Proxy.
 void hotswap_removeObjectSwapListener(ProxyEventListener l)
          Removes the given listener of ProxyObjectSwapEvent notifications.
 void hotswap_setConstructorArguments(Object[] args)
          Sets the object constructor arguments.
 void hotswap_setConstructorParameters(Class[] params)
          Sets the object constructor parameters.
 Object hotswap()
          Attempts a hotswap transaction.
 

Method Detail

hotswap_getProxyClass

public ProxyClass hotswap_getProxyClass()
Returns the parent ProxyClass.

hotswap

public Object hotswap()
Attempts a hotswap transaction. If it succeeds, the new instance will be returned. Otherwise, the old (current) instance will be returned.

hotswap_getInstance

public Object hotswap_getInstance()
Returns the contained Object without trying to hotswap.

hotswap_getStatus

public int hotswap_getStatus()
Equivalent to hotswap_getProxyClass().getStatus().

hotswap_enqueue

public void hotswap_enqueue()
Explicitly enqueues this Proxy as a participant in the next hotswap transaction in the parent ProxyClass. This will be done automatically after each commit or rollback if the isAutoEnqueue property is set to true. The proxy.hotswap() calls this method as well, so it is not necessary to use unless you want to queue up several Proxy instances to be hotswapped in the same transaction.

hotswap_dequeue

public void hotswap_dequeue()
Explicitly dequeues this Proxy as a participant in the next hotswap transaction in the parent ProxyClass.

hotswap_isEnqueued

public boolean hotswap_isEnqueued()
Returns true if this Proxy instance is registered as a participant in the next hotswap transaction.

hotswap_release

public void hotswap_release()
Explicitly releases any resources associated with this Proxy. It usually not necessary to worry about having to explicitly release a Proxy; it is required only if one of the following two conditions are true:
  • The Object po returned by the hotswap_getInstance() method is known to be an instanceof ProxyObject AND it is known that the implementation of po.hotswap_onRelease() requires explicit release (even when not within the context of a hotswap transaction). This implementation behavior is not recommended. Your object should have a different method that is exposed on the object itself to do any non-hotswap-transaction related cleanup.
  • po.isAutoEnqueue() returns true. If a Proxy instance is autoenqueueing, it is always registered with the parent ProxyClass as a hotswap transaction participant. Of course, if the parent ProxyClass always contains a reference to this object, it will never be garbage collected. Calling this method ensures that the parent ProxyClass does not hold any references to this Proxy and hence will presumably be garbage-collectable.

  • hotswap_getConstructorArguments

    public Object[] hotswap_getConstructorArguments()
    Returns the object constructor arguments or null if none have been specified. These are passed to the java.lang.reflect.Constructor during object reflection.

    hotswap_getConstructorParameters

    public Class[] hotswap_getConstructorParameters()
    Returns the object constructor parameters or null if none have been specified. These are used select the correct java.lang.reflect.Constructor from the corresponding Class.

    hotswap_setConstructorArguments

    public void hotswap_setConstructorArguments(Object[] args)
    Sets the object constructor arguments.

    hotswap_setConstructorParameters

    public void hotswap_setConstructorParameters(Class[] params)
    Sets the object constructor parameters.

    hotswap_addObjectSwapListener

    public void hotswap_addObjectSwapListener(ProxyEventListener l)
    Adds the given listener of ProxyObjectSwapEvent notifications.

    hotswap_removeObjectSwapListener

    public void hotswap_removeObjectSwapListener(ProxyEventListener l)
    Removes the given listener of ProxyObjectSwapEvent notifications.