Remote System Explorer DataStore
Release 3.2

org.eclipse.dstore.core.java
Class RemoteClassLoader

java.lang.Object
  extended by java.lang.ClassLoader
      extended by org.eclipse.dstore.core.java.RemoteClassLoader

public class RemoteClassLoader
extends ClassLoader

This class loads a class from a remote peer. This classloader is used just as any other classloader is used. However, when instantiating the RemoteClassLoader, a DataStore is associated with it. The RemoteClassLoader goes through the following steps when trying to load a class: 1) Attempts to load the class from memory. Any class that had been loaded already this session would reside here. 2) Attempts to find the class using its parent classloader. 3) If caching preference is turned on: a) Attempts to find the class from the disk cache. 4) Requests the class, through the DataStore, from the remote peer. Waits for response. 5) If class cannot be found, throws ClassNotFoundException 6) If class is found, loads the class. 7) If caching preference is turned on: a) Caches new class in the disk cache for use in the next session. Notes: i) If there are one or more classes on which the target class depends, the RemoteClassLoader will attempt to load those classes too (possibly remotely), before loading the target class. ii) Since most implementations of Java use lazy classloading, the JVM may not attempt to load all required classes for the target class during class definition or instantiation. However, if the RemoteClassLoader was used to load the target class, then at any time, any additional classes required by the target class will be loaded using the RemoteClassLoader. Clients should be aware that this could trigger class requests and class transfers during the operation of objects of the target class, not just during definition and instantiation of it. iii) On the remote peer side, if you wish a class to be a candidate for transfer using the RemoteClassLoader on the opposite side of the connection, you MUST register the classloader for that class with the DataStore corresponding to the DataStore with which the RemoteClassLoader was instantiated. For example, in a client-server connection there is a "client" DataStore and a corresponding "server" DataStore. Suppose the server wishes to use the RemoteClassLoader to load class A from the client. Suppose A is loaded on the client using ClassLoaderForA. On the client side, ClassLoaderForA must be registered with the "client" DataStore so that when the class request for A comes in from the server, the client DataStore know how to load class A. Caching: To set your preference for caching, on either the client or server DataStore, use the following command: _dataStore.setPreference(RemoteClassLoader.CACHING_PREFERENCE, "true"); The cache of classes is kept in a jar in the following directory: $HOME/.eclipse/RSE/rmt_classloader_cache.jar To clear the cache, you must delete the jar. Threading Issues: It's safest to use the RemoteClassLoader on a separate thread, and preferably not from the CommandHandler or UpdateHandler threads. The RemoteClassLoader uses those threads to request and send the class. However, DataStore commands can be structured such that safe use of the RemoteClassLoader on these threads is possible. See below for an example. Using the RemoteClassLoader in your subsystem miner: Suppose you want the client to be able to kick off a class request in your host subsystem miner. In order to accomplish this, you would take the following steps: 1) Add a command to your miner in the extendSchema() method. 2) Add logic in the handleCommand() method to route command to another method when handleCommand receives your new command. 3) In your command handling method, get the name of the class to load from the subject DataElement. 4) Load the class using the RemoteClassLoader. 5) Make sure the class you are attempting to load exists on the client and that class's ClassLoader is registered with the DataStore!


Nested Class Summary
protected  class RemoteClassLoader.LoadClassThread
          A new thread for loading classes in.
 
Field Summary
static String CACHING_PREFERENCE
           
 
Constructor Summary
RemoteClassLoader(DataStore dataStore)
          Constructor
 
Method Summary
protected  Class findClass(String className)
          Finds the specified class.
 void loadClassInThread(String className)
          Causes a new thread to start in which the specified class is loaded into the repository.
 void receiveClass(String className, byte[] bytes, int size)
          Receives a class sent by a remote agent and loads it.
 Class requestClass(String className)
          Requests a class (synchronously) from the client
protected  void requestClassInThread(String className)
          Kicks off a separate thread in which to request the class, rather than doing it synchronously.
 boolean useCaching()
           
 
Methods inherited from class java.lang.ClassLoader
clearAssertionStatus, defineClass, defineClass, defineClass, definePackage, findLibrary, findLoadedClass, findResource, findResources, findSystemClass, getPackage, getPackages, getParent, getResource, getResourceAsStream, getResources, getSystemClassLoader, getSystemResource, getSystemResourceAsStream, getSystemResources, loadClass, loadClass, resolveClass, setClassAssertionStatus, setDefaultAssertionStatus, setPackageAssertionStatus, setSigners
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHING_PREFERENCE

public static final String CACHING_PREFERENCE
See Also:
Constant Field Values
Constructor Detail

RemoteClassLoader

public RemoteClassLoader(DataStore dataStore)
Constructor

Parameters:
dataStore - A reference to the datastore to be used by this RemoteClassLoader.
Method Detail

useCaching

public boolean useCaching()

findClass

protected Class findClass(String className)
                   throws ClassNotFoundException
Finds the specified class. If the class cannot be found locally, a synchronous request for the class is sent to the client, and the calling thread waits for a response. If the client can find the class, it sends it back to the server. The server receives the class in a new thread, defines it, and then notifies this thread. The class is then returned by this method. If the class cannot be found, the client notifies the server, and this method throws a ClassNotFoundException.

Overrides:
findClass in class ClassLoader
Parameters:
className - the fully qualified classname to find
Returns:
the loaded class
Throws:
ClassNotFoundException - if the class cannot be found on either the client or the server.

receiveClass

public void receiveClass(String className,
                         byte[] bytes,
                         int size)
Receives a class sent by a remote agent and loads it. Notifies all threads waiting for this class to load that the class has been loaded.

Parameters:
className - the name of the class to receive
bytes - the bytes in the class
size - the size of the class

requestClassInThread

protected void requestClassInThread(String className)
Kicks off a separate thread in which to request the class, rather than doing it synchronously.

Parameters:
className - The fully qualified name of the class to request.

requestClass

public Class requestClass(String className)
                   throws ClassNotFoundException
Requests a class (synchronously) from the client

Parameters:
className - The fully qualified name of the class to request.
Returns:
the requested class
Throws:
ClassNotFoundException - if the class was not found on the client

loadClassInThread

public void loadClassInThread(String className)
Causes a new thread to start in which the specified class is loaded into the repository. This method usually returns before the class has been loaded.

Parameters:
className - The fully qualified name of the class to load

Remote System Explorer DataStore
Release 3.2

Copyright (c) IBM Corporation and others 2000, 2010. All Rights Reserved.