User Manual    [Previous]   [Next]   

Basic Distributed Systems

By default, compiling an Umple system will result in set of classes that execute as a single application operating on objects that exist in a single Java virtual machine (VM) on a single computer (node). In this default mode of operation all method calls are made locally to methods in the same running VM.

However, by using the 'distributable' keyword, modelers can instruct the Umple compiler to allow objects to be distributed to multiple running VMs most likely running on different computers (although they can be on the same computer if desired). In this mode, some method calls result in remote invocation of methods in a different VM using either Remote Method Invocation, or Web Services.

To make an Umple model into a distributable one that runs on multiple VMs, the developer needs to perform the following. Each of these steps is described in more detail later.

1. Identify the distributable classes by adding distributable; to such classes.
2. Decide on groups of objects that are to exist together on a given VM by grouping them into different runtime components
3. Identifying the VMs and the groups of objects that must run on each VM using a configuration file.
4. Run each VM.

Distributable classes

The developer must first identify which classes are allowed to have objects on multiple machines using the 'distributable' keyword. For example:

class Customer{

   distributable;

}

The above need not require modifying the original code as it could be introduced using a mixin. Indeed it is possible in Umple to turn a non-distributed system into a distributed system with a minimum of code change.

The distributable feature is inherited by subclasses. One can also put distributable in an interface (It makes the classes that use this interface distributable). Human and Customer are both distributable in the example below.

class Human{

  distributable;

}

class Customer{

   isA Human;

}

Runtime components

Objects can be grouped to run on the same machine. These groups are called runtime components. By default, all instances of the same class are grouped together in a runtime component named after the class name. For example all of the objects of the Customer class above would be in the Customer runtime component.

The runtime components are managed by a special class that Umple creates called UmpleRuntime. An instance of UmpleRuntime will exist on each running VM. It is mostly invisible to the program; it is only called by the program in a few special circumstances.

To put a specific instance of a class in a different group, one can name the runtime component of the object as the last parameter of the constructor when creating the instance of the distributable class.

In the example below, "customer1" goes into the runtime component "Customer" by default.

Customer customer1= new Customer ("customer 1");

In the example below, we put "v" in the runtime component "Customer".

Vendor v= new Vendor ("Vendor 1", UmpleRuntime.getComponent("Customer"));

The names of the runtime components can be any alphanumeric word and there is no need to declare them at compile time or in the configuration file. In the example below, we put "v" in the runtime component "Component1" which is not named after any class.

Vendor v= new Vendor ("Vendor 1", UmpleRuntime.getComponent("Component1"));

An Umple program using distributed objects can call methods on an object that happens to exist in another VM. Arguments can also be passed containing objects that are on another VM. Behind the scenes proxy objects are used to make this happen, and method calls use Remote Method Invocation (RMI) by default, or else web services if specified as discussed below.

Configuration file

As mentioned above, the UmpleRuntime class is generated for every distributed system. The instance of UmpleRuntime on each VM is responsible for distributing the objects. It reads a file (by default configuration.txt) to know which VM is where, and which VM and runs which runtime components.

In the configuration file, one declares a machine using curly brackets ({}) and can define specifications of the machine in the brackets (id, ip, url,..) as shown in the example below. One also names the runtime components that the machine runs.

The first example shows a configuration file with four nodes and five runtime components.

{id=0 ip=192.168.2.1 port=10541 {rc1}}

{id=1 ip=192.168.2.2 {rc2, rc3}}

{{Vendor} ip=192.168.2.3 id=2 }

{id=3 ip=192.168.2.4 {Warehouse}}

The next example is a configuration file with two nodes on the same physical machine with different ports to distinguish them.

{id=0 ip=192.168.2.1 port=10541 {rc1}}

{id=1 ip=192.168.2.1 port=10540 {rc2, rc3}}

Finally, the following shows configuration file with all runtime components on the same node

{id=0 url=http://localhost  port=10541 {rc1, Vendor, rc2, rc3}}

Running the system

To run the system, the operator starts Java VMs for as many copies of the system as he or she desired by invoking a main class (a class with a main method). At least one of the started machines must be started using such a main class; other machines can be started by running UmpleRuntime on those machines.

The id of the machine must be communicated to the UmpleRuntime as an argument. The example below shows two different machines being started where the Java code generated by umple is in the ecommerce directory. One VM is started by running a class called Main; this starts the whole system. The other one runs Umpleruntime on machine 1.

On machine 0:

java ecommerce.Main

On machine 1:

java ecommerce.UmpleRuntime 1

It is also possible to change the configuration file's default address:

java ecommerce.UmpleRuntime 1 c:\configFile.txt

The system will not do anything until all of the VMs in the system have started and connected.

The user can change the defaults by calling certain UmpleRuntime static methods from the main method.

UmpleRuntime.setThisNodeId(1); 

UmpleRuntime.setFileAddress("otherconfigFile.txt");

UmpleRuntime.getInstance();

More options

One can set all classes to be distributable by using the following directive:

distributable forced;

One can forbid all classes to be distributable by using the following directive:

distributable off;

One can use Web services instead of RMI by adding ws after distributable keyword in the class:

distributable WS;

More examples and details about the distributable feature will be provided shortly.