XN Handbook

Brought to you by the good folks at

An engineer's practical guide to the XN Framework.

Development Environment

  • Fully configured VM, running the XN Framework stack.
  • Requirements:
    • Vagrant with VirtualBox or VMWare Fusion provider.
    • RubyGems - Installing the xnlogic command-line tool.

On the host machine, use                                  to generate

  • Application directory structure and starter code.
  • VM configuration.
xnlogic application

On the VM, which you can access using                    .

  • Run the server. 
  • Test interactively, using the xn-console.
  • The application code is mounted as a shared folder.
xnlogic ssh

Setting up your development environment

~$ gem install xnlogic
  1. Install Vagrant.
  2. Install RubyGems.
  3. Install the xnlogic command line tools.

The xnlogic command-line tool

~$ xnlogic application my_app --key my_xn_user:password

Create a new application

~/my_app$ xnlogic up

Start the VM, for an existing application.

~/my_app$ xnlogic ssh

Log into the VM.

~/my_app$ xnlogic halt

Stop the VM (can be restarted later, using xnlogic up)

~/my_app$ xnlogic destroy

Destroy the VM (i.e. Stop it and delete all files).

 * On slower computers, can be used to free resources when not using the VM.

 * Free hard-drive space, taken by the VM image.

 * In dev environment, the database will be deleted, as it is stored on the VM.

~$ xnlogic help

More info

 * The mounted directory (which lives on the host machine) is not deleted.

The Generated Application Directory

~/my_app$ ls
config     Gemfile       lib             Readme.md  torquebox_init.rb
config.ru  Gemfile.lock  my_app.gemspec  spec       torquebox.yml
dev        Jarfile.lock  Rakefile        tasks      Vagrantfile
~/my_app$ ls lib/my_app
fixtures.rb   models.rb  permissions.rb  type.rb
initializers  parts      type            version.rb
  • lib - Your application code.
  • spec - Automated test code.
  • config

Your application code:

The VM

Where Development Happens ...

What's In The VM?

  • Software dependencies.
    JRuby, Java, XN Framework gems, etc.
  • Graph database.
    Default is Neo4j.
  • Mounted application code.
  • TorqueBox - Web Application Server.
  • Datomic - Database used for the history graph.
  • Useful scripts and command-line tools.

The full stack:

Getting Around The VM

➜  ~  ls
bin  my_app  tmp  xn.dev

~/my_app is mounted from the host machine:

➜  ~  xn-console

Test your code interactively

➜  ~  xn-server

Or run it in a server.

The xn-console loads the full stack and allows you to:

  • Interactively write queries (using the Pacer library).
  • Simulate API calls.
  • Manage databases, users and groups.

Using The xn-console

 > PM.create_client('my_app', 'db01')

Create a database.

 > app = PM['db01']

Get the application (given an existing database name).

 > g = app.graph

Get the underlying graph object.

 > g.v.out_e.in_v

Run queries on the graph.

 > g.v(MyApp::M::User, {username: 'lenora'}).follows.tweets.count
 > MyApp.reload!

Reload code changes.

Using The xn-console

 > include app.console

Enable simulating API calls from the console.

 > xget '/model'

Simulate API calls.

 > xpost '/model/user/id/73/action/follow', {user_id: 79}
 > xdelete '/model/user/id/143'
 > hg = app.history_graph

Get a reference to the history graph.

Run queries on the history graph.

 > u = hg.v(MyApp::M::User, Pacer::Temporal).first
 > u.tweets.count
 => 5
 > u.at_time(u.first_transaction.time).tweets.count
 => 0

Outside Of The xn-console

➜  ~ sudo service datomic status

Manage the Datomic service (used for the History Graph)

➜  ~ ls xn.dev/tmp/server.log

Server log.

➜  ~  ls /opt/xn_apps
admin_token          datomic.data  datomic.pid
authenticator_token  datomic.log   my_app

XN Data folder.

Kill hanging programs (e.g. after unexpected shutdown).

➜  ~  xn.dev/script/killer

Database data files (all databases of the my_app application).

➜  ~  ls /opt/xn_apps/my_app

Resources

Made with Slides.com