JanosVM v0.6.0 Java API

## edu.utah.janosvm.resources
Class NameSpaceResource

    java.lang.Object
      |
      +--edu.utah.janosvm.resources.NameSpaceResource

public final class NameSpaceResource
extends java.lang.Object

Provides access methods to the current team's root name space.

A standard JVM provides a root name space to contain system classes and some/all user classes for the program, similarly, the JanosVM provides a root name space for each team in the system. However, a team doesn't exist in isolation so it must be able to cooperate with, at least the kernel team, or other server teams. Therefore, we must provide a mechanism for sharing classes between teams so that they can function and still obey the type rules of java. We might be able to accomplish this by using class loader magic but this could quickly become confusing and could force odd restrictions on what classes teams could share with each other. The current solution is to create an abstraction at a lower level then a class loader, the class group, which acts as a container for a loosely related set of classes. In addition, each class group can have a number of view groups which can map the real names of the classes to something more appropriate for the team using the classes. We hope the combination of class groups and view groups will provide a sufficiently flexible and secure way of sharing classes between teams without resorting to more confusing and possibly restrictive class loader magic.

#### Class Groups

Internally, the NameSpaceResource manages "class groups" which are a set of loosely related classes loaded into a team. Each team has at least two class groups, the internal group which contains all classes that have been loaded directly into the team, and the kernel group which contains any base classes that the VM internals manipulate (java.lang.Object, java.lang.String, etc...). In addition, server teams can export a set of classes which can then be imported by their clients. The set of classes that belong in a group is described by a classgroup section of the config file and stored internally (in C) as a ClassGroupType. The set of classes that need to be shared is up to the implementor of the JanosVM server software, most likely this would include any Importables and their support classes. Since the group type only describes which classes should be shared and does not do the actual exporting and importing, a team must be responsible for the classes and any state they need to function. Exporting a group type is simply a matter of calling NameSpaceResource.exportClassGroup(String) with the name of the desired group type as listed in the config file. The corresponding class group can then be imported by passing a NameSpaceSpec with a NameSpaceGroup that refers to the exporting team, the group type name, and the view with which the new team should see these classes.

#### View Groups

The possibility of name clashes in this class sharing mechanism led to the development of the view group and, in fact, is the one reasons for putting classes into groups instead of managing them individually. The main example of name clashing has to do with JanosVM not providing a real java runtime, but still using `java.lang.*` since this is what Kaffe used internally and all the development tools use. If a real java runtime was written for JanosVM then it would probably want its own version of the java.lang classes instead of the JanosVM specific ones. A possible solution is to provide a view group for the kernel classes that mapped the class names to something more unique, but still retaining their identity as the real JanosVM version of the classes. However, mapping names is complicated by the fact that classes don't live an isolated existence, since their fields and methods reference related classes, hence the need to group them together. The actual mapping is specified as the real class name followed by the mapped name in a viewgroup section of the config file and is then stored internally as a ViewGroupType within the ClassGroupType. By default, every class group has an "identity" view group which, as you might expect, makes the classes available under their builtin names. For example, the following config file section describes the class group "myServer" and its "emulateBlah" view group which maps the "myServer" class names so as to emulate similar set of classes.

     %begin namespace-resource
       %begin classgroup myServer
         Foo
         FooHandle
         %begin viewgroup emulateBlah
           Foo Blah
           FooHandle BlahHandle
           %end
         %end
       %end

#### Restrictions

A classgroup should really only contain the set of classes that are to be exposed to the client team. If exposed classes are left out or not mapped in the view properly it will leave an opening for classes to be spoofed. Currently, the resource will check to make sure that any classes referenced by public/protected methods are also imported into the team. This should help ensure that nothing is missing, however, it currently doesn't check that the imported class is the same one that was used in resolution in the original name space.

#### The Future

Currently, classes can only be exported from and imported into the root name space of the team. This might be generalized so that class groups can be managed by individual class loaders.

Author:
  Tim Stack, Utah Janos Team
See Also:
  `exportClassGroup(String)`, `NameSpaceSpec`, `NameSpaceGroup`

Method Summary
`static void` `exportClassGroup(java.lang.String type)` Export a ClassGroup from the current team by loading the classes, collecting them under the internal class group object, and making them available for other teams to use.
`static java.lang.Class` `loadTeamClass(java.lang.String className)` Load a class into the root ClassLoader of the current team.
`static java.lang.Class` `loadTeamClass(java.lang.String className, boolean initialize)` Load a class into the root ClassLoader of the current team.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### exportClassGroup

    public static void exportClassGroup(java.lang.String type)
                                 throws java.lang.ClassNotFoundException,
                                        ClassGroupNotFoundException,
                                        InvalidClassGroupException

  Export a ClassGroup from the current team by loading the classes, collecting them under the internal class group object, and making them available for other teams to use.

  ClassGroups are defined in the JanosVM configuration file. A ClassGroup must be an internally consistent set of classes that can be safely shared between Teams. That is, all classes referenced by any class in a ClassGroup must be satisfied by that ClassGroup or by a class in another ClassGroup which is also exported to this team.

  Parameters:
    `type` - The name of a classgroup section in the config file.

### loadTeamClass

    public static java.lang.Class loadTeamClass(java.lang.String className)
                                         throws java.lang.ClassNotFoundException

  Load a class into the root ClassLoader of the current team.
  Parameters:
    `className` - The name of the class to load.
  Throws:
    Throws - ClassNotFoundException if the class couldn't be found.

### loadTeamClass

    public static java.lang.Class loadTeamClass(java.lang.String className,
                                                boolean initialize)
                                         throws java.lang.ClassNotFoundException

  Load a class into the root ClassLoader of the current team.
  Parameters:
    `className` - The name of the class to load.
    `initialize` - Initialize the class.
  Throws:
    Throws - ClassNotFoundException if the class couldn't be found.

JanosVM v0.6.0 Java API

This documentation is Copyright (C) 2000-2002 The University of Utah. All Rights Reserved. See the documentation license for distribution terms and restrictions.
Documentation, software, and mailing lists for the JanosVM can be found at the Janos Project web page: http://www.cs.utah.edu/flux/janos/
Generated on Mar 17, 2002