one.world – FAQ


Sections


Building one.world

How do I build the Java class files?
Execute "make" in the top-level development directory. This builds all Java class files.

How do I build the documentation?
Execute "make doc" in the top-level development directory. This builds all documentation.

How do I build the GUID DLL?
Execute "make guiddll" in the one/util source directory. On Windows, you need to have the Visual C command line tools installed.

How do I build the JAR files for the binary release?
Execute "make jar". This builds the JAR files and places them into the release/bin directory.

How do I re-build all binaries and documentation from scratch?
Execute "make clobber" in the top-level development directory and then make the Java class files, JAR files, and the documentation again. The GUID DLL is not removed by clobbering.

When building on Windows, I get a "System cannot find the path specified" error. What gives?
You need to use the "--win32" flag when using make on Windows. Also, note that on Windows the build tools need to be installed in directories that do not contain white spaces or punctuation characters.

When building on Windows, I get a "make: *** No rule to make target `C:\Documents'" error. What gives?
The paths for the build tools, source files, and binaries must not contain spaces. make gets confused by them. You can, however, use Window's subst command to assign a drive letter to a path containing spaces (execute "subst /?" to see its usage information). Your development tree may still not contain any file or directory names with spaces in them, but the path to the development tree may. For example, if your development tree is in "C:\Documents and Settings\user\java", execute

    subst K: "C:\Documents and Settings\user\java"
and then set the JAVA_DEV_ROOT environment variable to K:\.

When building the documentation, I get a "Error reading file: [...] package-list" error. What gives?
javadoc needs the Java SDK's package list file for generating the correct links to SDK documentation. You can either install the Java 2 SDK documentation or put this file into the docs/api directory of your Java installation.

When building, I get a "Makefile:65: *** commands commence before first target. Stop." error. What gives?
GNU make has a bug and under certain circumstances get's confused by carriage returns in make files. As a work-around, either remove all carriage returns from the offending make file by executing 

   tr -d '\r' <INFILE >OUTFILE
or add an extra space between the Java file name and the '\' on the previous line.


Running one.world

How do I run one.world?
To run one.world, execute "one.world" on Windows and "source one.world.sh" on Linux (binary and source release). Starting one.world also starts the Emcee application, which provides a graphical user interface for managing users and their applications. To run the regression tests, execute "java one.fonda.Exercise" (source release only).

When running one.world code, I get a "no one_util_Guid in java.library.path" error. What gives?
You need to build the GUID DLL by executing "make guiddll" in the one/util source directory. See the corresponding question in the building one.world section.

When running one.world code, I get a "Can't start up system: java.io.FileNotFoundException: one.world.config" error. What gives?
one.world uses configuration parameters, which are expressed as Java system properties and specified in a configuration file. By default, that file is called "one.world.config" and is located in the current directory. You need to make sure the configuration file exists in the directory in which you are starting one.world. The configuration page describes the configuration options in more detail.

When running one.world code, I get a "[...]/__db.001: No such file or directory – Can't start up system: java.io.IOException: Can't open the database" error. What gives?
The path specified by the one.world.store.root system property (see previous question) does not exist. Make sure that all directories specified by the path exist and then try again.


Writing Applications for one.world

What's the deal with tuples?
Data in one.world are represented in the form of tuples, which can be statically typed or dynamically typed. Statically typed tuples basically are Java objects, whose instance fields are all public. The specification is somewhat more involved, but the Tuple abstract base class takes care of most requirements. Dynamically typed tuples are instances of DynamicTuple.

What's the deal with all these events and event handlers?
one.world uses asynchronous events instead of synchronous method invocations. Events are processed by event handlers and are passed by value. In other words, after passing an event to an event handler, the caller must not retain any references to it. Note that events are also tuples.

What's the deal with components?
Functionality in one.world is implemented in the form of components. Components export and import event handlers, which are statically declared in the constructor of the component, but dynamically linked with other components. Components are always instantiated in a specific environment (see next question).

What's the deal with environments?
Environments are containers for stored tuples, active computations, and other environments. They are the main abstraction for structuring the system. The functionality for a computation is provided by the components that are instantiated in a given environment.

How do components interact with their environment?
Environments are also components; application components interact with their environment by linking with it. Environments expose the following three event handlers:

  • An imported "main" event handler, which notifies an environment's main application component of state changes, such as when the environment is activated or about to be terminated.
  • An exported "request" event handler, which accepts arbitrary events. It is typically used by the application to request operations on environments – such as moving an environment – and to request to bind a resource – such as tuple storage.
  • An imported "monitor" event handler, which lets an application monitor all requests issued by descendant environments.
Before an application can run, it's main component must at least be linked with its environment's main event handler.

As stated in the previous answer, an application's main component needs to be linked with its environment's main event handler. What events does it need to handle?
It needs to handle at least the following events.

  • ACTIVATED environment events indicate that the environment has been activated and that the application can now bind to resources and perform its work.
  • RESTORED environment events indicate that the environment has been restored from a saved check-point. The application can now bind to resources and perform its work.
  • MOVED environment events indicate that the environment has been moved to a new location on a different node. The application can now bind to resources and perform its work.
  • CLONED environment events indicate that the environment has been cloned from another environment. The application can now bind to resources and perform its work.
  • STOP environment events indicate that the application's environment is about to be terminated or destroyed. The application must release all bound resources and stop all on-going computations. When the application is ready to be terminated or destroyed, it needs to reply with a STOPPED environment event.

Writing components is a little repetitive; they have the same basic structure and require all these descriptors. Can you help?
We have a utility program to generate skeleton source files for components. The program is one.tools.Skeletor. It takes as its only input the name of the file containing a simple description of the component and then generates the corresponding source file. For example, when executing 

    java one.tools.Skeletor component
you get this source file.

Furthermore, the one.gui package provides support for building GUI-based applications. Notably, Application significantly simplifies the implementation of an application's main component, and GuiUtilities implements several static helper methods for managing GUIs.

I've written the components for my application and a main component to interact with the application's environment. How does my application get initialized?
You need to write an initializer method, typically as part of your application's main component. This method must have 

    public static void init(Environment, Object);
as its signature, where the environment is the environment the application will be running in and the object is a closure. Inside this method, you instantiate all your application's components and link them (including to the environment). This initializer is invoked when executing the mk or load commands in the root shell or when completing the "Run..." dialog from a user's popup-menu in Emcee. Note that the closure passed to the initializer by the root shell and by Emcee always is an array of strings. Also note that an application's initializer may throw any Java throwable to signal that it could not properly initialize the application. In that case, the environment's imported event handlers are automatically unlinked, which effectively undoes all operations performed by the initializer.

How does one.world access my application's code?
To run your own applications in one.world, you need to make the Java class or JAR files accessible within one.world. This entails (a) adding them to the classpath and (b) changing the security policy.

To add a directory with class files or a JAR file to the classpath for the source release, you need to add the directory or JAR file name to the CLASSPATH environment variable. For the binary release, you need to edit the one.world.bat (on Windows) and one.world.sh (on Linux) files. Both files contain a line that starts with "java -cp". You need to add the directory or JAR file to the list of paths following the "-cp" flag.

To change the security policy, you need to edit the one.world.policy file. It is in the root directory of the source release and the config directory of the binary release. The policy contains a block of permission statements that grant java.io.FilePermissions and that is prefixed with a comment saying "Add the directories with application-specific class files [...]".

This is where you need to add corresponding permission statements for the directory or JAR file containing your application. For example, to make the "bin\my-classes" (on Windows) or "bin/my-classes" (on Linux) directory accessible, add the following:

  permission java.io.FilePermission "bin${/}my-classes", "read";
  permission java.io.FilePermission "bin${/}my-classes${/}-", "read";

To make the "bin\my-classes.jar" (on Windows) or "bin/my-classes.jar" (on Linux) JAR file accessible, add the following:

  permission java.io.FilePermission "bin${/}my-classes.jar", "read";

Note that the separator character, '\' on Windows and '/' on Linux, is always replaced with "${/}".


Debugging in one.world

When sending an event to an event handler, my code receives a NotActiveException. What's going on?
There are five reasons why your code can receive a NotActiveException:

  • The environment hosting the event handler has not yet been activated.
  • The environment hosting the event handler was active, but has been terminated.
  • The environment hosting the event handler has been restored from a saved check-point.
  • The environment hosting the event handler has been destroyed.
  • The environment hosting the event handler has moved to another node.


Licensing one.world

What's the license for one.world?
one.world is generally licensed under the BSD license. Exceptions are the make files and the eval regression tests, which are licensed under the GNU GPL. Furthermore, the GUID DLL sources for Linux have their own license. The appropriate license information is contained at the beginning of each source file.

What's the license for the libraries one.world uses?
Sleepycat's Berkeley DB has its own open source license. Markus Dahm's Byte Code Engineering Library is available under both the GNU LGPL and the Mozilla Public License.