Using resources

When a worker starts up it can make use of file system and networking resources using the plugin IWorkerResourceProvider. This is provided by the Worker netlet:

public interface IWorkerResourceProvider
{
    /** Bind a resource previously allocated to the provider (worker).
     * @param resource_name  Previously set resource name.
     * @param service   Reciprocating consumer service session. */

    public IService bindResource(String resource_name, IService service)
        throws BeatrixServiceException;

    /** Query which resource names have not been previously used
     * and hence need initialising.
     * @return  Fresh resources, labelled with the previously set names.
     */
    public String[] getFreshResources();

    /** Get startup argument, as set by the createWorker method of
     * of {@link org.jtrix.project.beatrix.handle.INodeHandle}.
     * NB: This is not used by the current Beatrix plugin architecture.
     */
    public Object getArgument();

    /** Specify a network provider for this netlet.
     * @param sf  Socket factory facet which will provide the networking.
     * @throws FacetBindException  If the node cannot bind the facet.
     * @throws ITrampolineFacet.InvalidSocketFactoryException
     *             If the socket factory is somehow inappropriate.
     */
    public void setSocketFactory(ISocketFactory sf)
        throws FacetBindException, ITrampolineFacet.InvalidSocketFactoryException;
    
    /** Insert new file system.
     * @param  prefix  The point at which we will see this file system.
     *             For example a <code>prefix</code> of "/data" will
     *             mean we can write a file called "/data/index.txt".
     *             (Assuming the file system is writable.)
     * @throws FacetBindException  If the node cannot bind the facet.
     * @throws ITrampolineFacet.InvalidMountPointException
     *             If the specified prefix is somehow inappropriate.
     */
    public void mountFileSystem(String prefix, IFileSystem volume) 
        throws FacetBindException, ITrampolineFacet.InvalidMountPointException;

    /** Utility class helping lookup */
    public static class Get
    {
        /** Get the only instance of this plugin in the given manager.
         * Only the first such plugin is returned. If there isn't one then
         * an ArrayIndexOutOfBoundsException is thrown.
         */
        public static IWorkerResourceProvider one(IPluginManager pm)
        {
            return ((IWorkerResourceProvider)pm.lookup(IWorkerResourceProvider.class)[0]);
        } 
    }
}

Here is an example:

import org.jtrix.base.IService;
import org.jtrix.facet.node.ISocketFactory;
import org.jtrix.facet.node.IFileSystem;

...

IWorkerResourceProvider wrp = (IWorkerResourceProvider)pluginManager()
    .lookup(IWorkerResourceProvider.class)[0];

IService disk = wrp.bindResource("disk", consumer_service_1);
IFileSystem fs = (IFileSystem) disk.bindFacet(IFileSystem.class.getName());
wrp.mountFileSystem("/home", fs);

IService net = wrp.bindResource("net", consumer_service_2);
ISocketFactory sf = (ISocketFactory)net.bindFacet(ISocketFactory.class.getName());
wrp.setSocketFactory(sf);

Once this is done the file system and socket factory can be used transparently.

Things to note are:

• The process of a worker getting a handle on one of its allocated resources is called binding. Hence the method called bindResource(). This is just like a consumer netlet binding a service with a warrant; it even gets an IService in return.
• A worker binds each kind of resource using the same label as the manager originally used.
• consumer_service_1 and consumer_service_2 are any reciprocating client services (IService), just like a consumer netlet binding a service with a warrant. We could have used createClientSession(false) from our IPeerSupport plugin.

Some notes on file system use:

• Only files within the /home hierarchy can be used in this example. We can call our files and directories /home/jim, /home/ulf/robots.txt, etc. Adding another file system with another prefix gives us another hierarchy.
• The prefix /home is entirely for our benefit. It has no bearing on what directories might be called in the underlying operating system.
• The prefix can only specify the top level directory; prefixes of /var/tmp and /usr/local are not allowed, while /var and /usr are.
• Jtrix sets the directory separator to be / (a single slash), regardless of the underlying operating system.
• The /proc hierarchy is given to us automatically; we don't have to bind or mount anything to access it, it's just there. This gives process-specific files. At the time of writing it contains two directories: runtime contains the Java runtime JAR, rt.jar; while codebase contains the other JARs currently in use by this netlet, each named with the label used to download it.^5.1