Releases, stable builds

You can download the binary format of the project from http://www.egothor.org/download/release/egothor/j5m-distribution/.

Snapshots, developer builds

If you are looking for the latest (and unstable) builds, you can also try http://www.egothor.org/download/snapshot/egothor/j5m-distribution/.

Installation

Grab the tar.gz archive from the repositories mentioned above and extract it in a folder. The archive structure is:

$ ls -naR
.:
total 28
drwxrwxr-x. 5 1000 1000 4096 Jun 27 17:43 .
drwxrwxr-x. 4 1000 1000 4096 Jun 27 17:43 ..
drwxrwxr-x. 2 1000 1000 4096 Jun 27 17:43 bin
drwxrwxr-x. 2 1000 1000 4096 Jun 27 17:43 etc
-rwxr-xr-x. 1 1000 1000  136 Jun 27 17:41 j5m
drwxrwxr-x. 2 1000 1000 4096 Jun 27 17:43 lib
-rw-rw-r--. 1 1000 1000 2914 May  9 21:41 LICENSE.txt
-rw-rw-r--. 1 1000 1000    0 Jun 26  2013 NOTICE.txt
-rw-rw-r--. 1 1000 1000    0 Jun 26  2013 README.txt

./bin:
total 348
drwxrwxr-x. 2 1000 1000   4096 Jun 27 17:43 .
drwxrwxr-x. 5 1000 1000   4096 Jun 27 17:43 ..
-rw-rw-r--. 1 1000 1000  20410 Jun 27 17:40 j5m-demo-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000  50902 Jun 27 17:39 j5m-fundamentals-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000  69335 Jun 27 17:39 j5m-kernel-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000  12360 Jun 27 17:40 j5m-ldapreg-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000  46669 Jun 27 17:40 j5m-mcastreg-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000 103067 Jun 27 17:40 j5m-nugget-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000  20679 Jun 27 17:39 j5m-starter-4.0.2-SNAPSHOT.jar
-rw-rw-r--. 1 1000 1000   7923 Jun 27 17:40 j5m-systools-4.0.2-SNAPSHOT.jar

./etc:
total 12
drwxrwxr-x. 2 1000 1000 4096 Jun 27 17:43 .
drwxrwxr-x. 5 1000 1000 4096 Jun 27 17:43 ..
-rw-rw-r--. 1 1000 1000 2910 Jun 27 17:41 policy-all.conf

./lib:
total 52
drwxrwxr-x. 2 1000 1000  4096 Jun 27 17:43 .
drwxrwxr-x. 5 1000 1000  4096 Jun 27 17:43 ..
-rw-rw-r--. 1 1000 1000 41123 Feb 13  2013 commons-cli-1.2.jar

Check the j5m script file in the root of the package and verify the version of the platform (4.0.2-SNAPSHOT in the listings above). Later, you can copy the newer version over the old one, just change the VERSION variable in the j5m file:

#!/bin/bash

VERSION=4.0.2-SNAPSHOT

java -Dj5m.bin=bin -Djava.security.policy=etc/policy-all.conf -jar bin/j5m-starter-${VERSION}.jar $*

The platform is launched by bin/j5m-starter-*.jar which is the executable JAR. It reads two variables:

  • j5m.bin - directory path with j5m binaries. The default script simply points to "bin" subdirectory.
  • java.security.policy - Java policy file. You can use or modify j5m default policy file etc/policy-all.conf.

Do it:

$ ./j5m -h
Jun 27, 2014 5:51:03 PM j5m.Start main INFO: Installing security manager
Jun 27, 2014 5:51:03 PM j5m.boot.Bootstrap execute INFO: Platform version: 4.0.2-SNAPSHOT
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap initializeClassLoaders INFO: using dependencies of version 4.0.2-SNAPSHOT
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap initializeClassLoaders INFO: fundamentals ClassLoader init
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap initializeClassLoaders INFO: kernel ClassLoader init
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap initializeClassLoaders INFO: SPI ClassLoaders init
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap lambda$initializeClassLoaders$1 INFO: found multicast registry service j5m.mcast.pool.MulticastSystemRegistryService in SecureSystemClassLoader{nick=bin/j5m-mcastreg-4.0.2-SNAPSHOT.jar@(http:j5m:spi <no signer certificates>)}
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap lambda$initializeClassLoaders$1 INFO: found ldap registry service j5m.ldap.pool.LdapSystemRegistryService in SecureSystemClassLoader{nick=bin/j5m-ldapreg-4.0.2-SNAPSHOT.jar@(http:j5m:spi <no signer certificates>)}
Jun 27, 2014 5:51:03 PM j5m.boot.ParanoiaBootstrap initializeClassLoaders INFO: nugget ClassLoader init
Jun 27, 2014 5:51:03 PM j5m.system.SystemDaemon initialize INFO: installing Ctrl-C hook
Jun 27, 2014 5:51:03 PM j5m.system.SystemJ5M initializeSystemProperties INFO: loading configuration from /home/user/.j5m
Jun 27, 2014 5:51:03 PM j5m.system.SystemJ5M initializeSystemProperties INFO: loading configuration from .j5m
Jun 27, 2014 5:51:03 PM j5m.system.SystemJ5M initializeSystemProperties INFO: reading system variables [wareProvider, warePrincipal, warePassword, wareObjectsDN, wareCfgDN, wareBootDN, fs]
Jun 27, 2014 5:51:03 PM j5m.system.SystemJ5M initializeFileSystems INFO: no shared filesystem defined
Jun 27, 2014 5:51:03 PM j5m.system.SystemJ5M initializeSystemRegistryService INFO: system registry providerId=multicast
Jun 27, 2014 5:51:03 PM j5m.mcast.pool.MulticastSystemRegistryService initialize INFO: multicast activated
Jun 27, 2014 5:51:03 PM j5m.mcast.pool.MulticastSystemRegistryService initialize INFO: [obj,cfg,boot] addresses 224.1.2.3:6789 224.1.2.3:6790 224.1.2.3:6791
Jun 27, 2014 5:51:04 PM j5m.nugget.DistributedRMIClassLoaderSpi register INFO: j5m.nugget.DistributedRMIClassLoaderSpi registered
Jun 27, 2014 5:51:04 PM j5m.mcast.pool.MulticastResourceManager installThreadGroup INFO: installing a new thread group java.lang.ThreadGroup[name=registry,maxpri=10]
Jun 27, 2014 5:51:04 PM j5m.mcast.pool.MulticastResourceManager installThreadGroup INFO: installing a new thread group java.lang.ThreadGroup[name=registry,maxpri=10]
Jun 27, 2014 5:51:04 PM j5m.mcast.pool.MulticastResourceManager installThreadGroup INFO: installing a new thread group java.lang.ThreadGroup[name=registry,maxpri=10]
Jun 27, 2014 5:51:04 PM j5m.system.SystemDaemon run INFO: system daemon class loader SecureSystemClassLoader{nick=fundamentals@(http:j5m:fundamentals <no signer certificates>)}
Jun 27, 2014 5:51:04 PM j5m.system.SystemDaemon run INFO: system daemon runs as ProtectionDomain  (http:j5m:fundamentals <no signer certificates>)
 SecureSystemClassLoader{nick=fundamentals@(http:j5m:fundamentals <no signer certificates>)}
 <no principals>
 java.security.Permissions@3407687 (
)


Jun 27, 2014 5:51:04 PM j5m.nugget.NuggetImpl directExec INFO: watchdog installed j5m.nugget.base.DistantInstance@4e6a30c8
Jun 27, 2014 5:51:04 PM j5m.mcast.net.MulticastReceiver initialize INFO: Starting receiver thread
Jun 27, 2014 5:51:04 PM j5m.mcast.net.MulticastReceiver$ReceiveRunnable run INFO: multicast receiver starts
Jun 27, 2014 5:51:04 PM j5m.mcast.net.MulticastRegistryProtocol initialize INFO: my identity 202c231b4de9650
Jun 27, 2014 5:51:04 PM j5m.mcast.net.MulticastReceiver$ReceiveRunnable installClassLoaderGetter SEVERE: installing a new class loader getter
Jun 27, 2014 5:51:04 PM j5m.mcast.net.MulticastRegistry bindReferenceToObject INFO: bind //domain1/controller/1403884263869@1315582152 to j5m.nugget.NuggetControllerImpl@7e837743 at 1403884263869 with null, lease 10,000 MILLISECONDS in j5m.mcast.net.MulticastRegistry@128adc8d
Jun 27, 2014 5:51:04 PM j5m.kernel.naming.EmbedRegistry store INFO: j5m.kernel.naming.EmbedRegistry@34ec11ea storing key //domain1/controller/1403884263869@1315582152
Jun 27, 2014 5:51:04 PM j5m.nugget.NuggetImpl tryBind INFO: exported //domain1/controller/1403884263869@1315582152
Jun 27, 2014 5:51:04 PM j5m.system.SystemDaemon run INFO: starting console
Jun 27, 2014 5:51:04 PM j5m.system.SystemDaemon run INFO: waiting for shutdown
//domain1/1403884263869 >

Now, you are in and you can enter your commands. Try shutdown to end the platform.

//domain1/1403884263869 > shutdown
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: new run level 0
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: new run level is not runnable, killing the objects
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: killing /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl kill INFO: disconnecting heartbeat and fencing /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl tryUnbind INFO: trying unbind /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl tryUnbind INFO: unexported //domain1/controller/1403884263869@1315582152
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl kill INFO: calling shutdown on /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl kill INFO: shutdown ended correctly /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl kill INFO: moved into dead-queue /controller
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: killing pool manager
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: run level activation finished 0
//domain1/1403884263869 > Jun 27, 2014 5:51:11 PM j5m.system.SystemDaemon run INFO: nugget finished
*** Ctrl-C registered
Jun 27, 2014 5:51:11 PM j5m.nugget.NuggetImpl setRunLevel INFO: new run level 0

The platform ended correctly, entering the run level 0. If you want to know more about the parameters you can pass into the starter, read its module documentation.

Now, let's deploy the demo application. Copy j5m-demo-*.jar into the /tmp directory - default policy file (etc/policy-all.conf) allows to read the application from the /tmp folder only.

$ cp bin/j5m-demo-4.0.2-SNAPSHOT.jar /tmp/demo.jar

Start the platform again and deploy the demo application. Issue the command in the console:

$ ./j5m
...
...
//domain1/1403885446170 > deploy app1 /tmp/demo.jar
OK: deploy app1:27956f1b00f6e179744e899163fca566339d3db8

The app1:27956f1b00f6e179744e899163fca566339d3db8 token is SHA based hash code that is unique for the deployed JAR archive. If you started another j5m instance, the code would be the same again and again unless you modify the JAR.

Context of our application is app1:27956f1b00f6e179744e899163fca566339d3db8. Now execute SayHelloImpl server object and bind it to /hello. Issue the following command:

//domain1/1403885446170 > exec /hello egothor.j5m.demo.SayHelloImpl app1:27956f1b00f6e179744e899163fca566339d3db8
Jun 27, 2014 6:17:24 PM j5m.nugget.base.SandboxingDomainCombiner <init> INFO: sandboxing on ProtectionDomain  (http:j5m:user:app1:27956f1b00f6e179744e899163fca566339d3db8 <no signer certificates>)
 app1:27956f1b00f6e179744e899163fca566339d3db8
 <no principals>
 null

Jun 27, 2014 6:17:24 PM j5m.nugget.base.DistantInstance invokeCallback INFO: invoke "startup" timeout=5,000
Jun 27, 2014 6:17:24 PM j5m.nugget.util.SafeInvoker invoke INFO: invoking an action and will wait for 5,000ms
Yahahahaha! :-)
Jun 27, 2014 6:17:24 PM j5m.nugget.base.DistantInstance invokeCallback INFO: finished "startup"
Jun 27, 2014 6:17:24 PM j5m.nugget.NuggetImpl directExec INFO: watchdog installed j5m.nugget.base.DistantInstance@7940309a
Jun 27, 2014 6:17:24 PM j5m.mcast.net.MulticastRegistry bindReferenceToObject INFO: bind //domain1/hello/1403885446170@2034249882 to egothor.j5m.demo.SayHelloImpl@7dd22e41 at 1403885446170 with null, lease 10,000 MILLISECONDS in j5m.mcast.net.MulticastRegistry@221a69bd
Jun 27, 2014 6:17:24 PM j5m.kernel.naming.EmbedRegistry store INFO: j5m.kernel.naming.EmbedRegistry@252f3060 storing key //domain1/hello/1403885446170@2034249882
Jun 27, 2014 6:17:24 PM j5m.nugget.NuggetImpl tryBind INFO: exported //domain1/hello/1403885446170@2034249882
OK: exec

Start a client object that is Runnable so j5m starts it in a separate thread:

//domain1/1403885446170 > exec /walker egothor.j5m.demo.Walker app1:27956f1b00f6e179744e899163fca566339d3db8
Jun 27, 2014 6:25:03 PM j5m.nugget.base.SandboxingDomainCombiner <init> INFO: sandboxing on ProtectionDomain  (http:j5m:user:app1:27956f1b00f6e179744e899163fca566339d3db8 <no signer certificates>)
 app1:27956f1b00f6e179744e899163fca566339d3db8
 <no principals>
 null

Jun 27, 2014 6:25:03 PM j5m.nugget.base.DistantInstance invokeCallback INFO: invoke "initialize" timeout=5,000
Walker context obtained
Jun 27, 2014 6:25:03 PM j5m.nugget.util.SafeInvoker invoke INFO: invoking an action and will wait for 5,000ms
Jun 27, 2014 6:25:03 PM j5m.nugget.base.DistantInstance invokeCallback INFO: finished "initialize"
Jun 27, 2014 6:25:03 PM j5m.nugget.NuggetImpl directExec INFO: allocating application thread group app1:27956f1b00f6e179744e899163fca566339d3db8
Jun 27, 2014 6:25:03 PM j5m.nugget.NuggetImpl directExec INFO: watchdog installed j5m.nugget.base.DistantInstance@5a566fc3
Jun 27, 2014 6:25:03 PM j5m.mcast.net.MulticastRegistry bindReferenceToObject INFO: bind //domain1/walker/1403885446170@1515614147 to egothor.j5m.demo.Walker@68003ae5 at 1403885446170 with [Lj5m.api.DistantParameter;@c314d87, lease 10,000 MILLISECONDS in j5m.mcast.net.MulticastRegistry@221a69bd
Jun 27, 2014 6:25:03 PM j5m.kernel.naming.EmbedRegistry store INFO: j5m.kernel.naming.EmbedRegistry@252f3060 storing key //domain1/walker/1403885446170@1515614147
Jun 27, 2014 6:25:03 PM j5m.nugget.NuggetImpl tryBind INFO: exported //domain1/walker/1403885446170@1515614147
OK: exec
//domain1/1403885446170 > zzzz? Hello!
zzzz? Hello!
...

Your console will be filled with "zzzz? Hello!" message that is produced by the Walker when it finds the server object (SayHelloImpl).

Let's kill the walker. First find its unique process id. It can be seen in "watchdog installed j5m.nugget.base.DistantInstance@5a566fc3" message above, but we try a bullet-proof method:

//domain1/1403885446170 > ps
Nugget:   //domain1/1403885446170 (-1 run-level)
Capacity: (3 heart-beat) (0 dead) (3 all)
Application spaces: 1
Chunks: #1 Alloc: 19 kB Requested: 19 kB Dedup ratio: 1.0
app1:27956f1b00f6e179744e899163fca566339d3db8 app1:27956f1b00f6e179744e899163fca566339d3db8

4F99543D e:LG SecureSystemClassLoader{nick=1403885446170@(http:j5m:nugget <no signer certificates>)} /controller
5A566FC3 e:LG app1:27956f1b00f6e179744e899163fca566339d3db8 /walker
7940309A e:LG app1:27956f1b00f6e179744e899163fca566339d3db8 /hello
=== LOG ===
[Friday, June 27, 2014 6:27:38 PM CEST] 1 //domain1/hello/1403885446170@2034249882 hosted at 1403885446170
...

The id is "5A566FC3", kill it:

//domain1/1403885446170 > kill 5A566FC3
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl kill INFO: disconnecting heartbeat and fencing /walker
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl tryUnbind INFO: trying unbind /walker
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl tryUnbind INFO: unexported //domain1/walker/1403885446170@1515614147
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl kill INFO: calling shutdown on /walker
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl kill INFO: shutdown ended correctly /walker
Jun 27, 2014 6:28:54 PM j5m.nugget.NuggetImpl kill INFO: moved into dead-queue /walker
OK: kill
//domain1/1403885446170 > Jun 27, 2014 6:28:54 PM j5m.nugget.base.DistantInstance kissOfDeath INFO: kissOfDeath interrupt "/walker"
Jun 27, 2014 6:28:54 PM j5m.nugget.base.DistantInstance kissOfDeath INFO: kissOfDeath join "/walker" 100ms
zzzz? Hello!
Jun 27, 2014 6:28:54 PM j5m.nugget.base.DistantInstance kissOfDeath INFO: kissOfDeath brutal, "/walker" ignores our soft touches

Walker is resistant, so it ignores Thread.interrupt() and Thread.join() requests, so that it is finally killed with a rather brutal Thread.stop().