2013/11/16

back to the beginning ... transports

Today I'm making good on my promise. We're going to make the res:/introduction/helloworld-xxxxx resources available in your browser. If the host you are running NetKernel on is open to the Internet, we might even make them available to the whole world !

I've had some questions about it so I want to repeat one point I made. The last two posts did cover the core of Resource Oriented Computing ! There really is no more. You do have all the building blocks and not unlike those in Lego they are simple. There is however no - practical - limit to what you can build with them.


Before we start making changes to our introduction module, I first have to explain about transports. NetKernel provides a Resource Oriented ... abstraction or box or - my personal view as a former System Administrator - operating system and until now we were only able to request the resources inside that with the Request Resolution Trace Tool. I bet that is not how you want to run your software. Transports solve this problem. A transport listens for incoming requests and brings them inside. The response (resource representation) goes the other way.

That may sound complex but again you are most likely already familiar with this concept. If you're a database administrator, you might know that an Oracle server listens on port 1521 for incoming database requests. The Apache server listens on port 80 for incoming http:// requests. The ssh daemon listens on port 22 for incoming ssh requests. Und so weiter.

As you can see thinking of NetKernel as an operating system was not so silly, for indeed, the transports it comes with work in exactly the same way. NetKernel has several transports available, out-of-the-box it has two running. On port 8080 and port 1060 it has Jetty (alternative for Apache) server based transports listening for incoming http:// requests.

The transport on port 8080 is also known as the FEF - Front End Fulcrum, the one on port 1060 as the BEF - Back End Fulcrum (or Administrative Fulcrum). For me personally this last acronym is confusing as BEF also stands for Belgian Franc (obsolete since 2002), I guess my age is starting to show.

You may already be able to deduce where this is going, these transports translate incoming http:// requests into res:/ requests.

For example :
  1. You request http://localhost:1060/tools/requesttrace in your browser.
  2. The transport listening on port 1060 translates this into a res:/tools/requesttrace request.
  3. The res:/tools/requesttrace resource can be found in the urn:org:netkernel:ext:introspect space (no worries about how I found that out).
  4. Therefore it must follow that the space that contains the transport - that would be urn:org:netkernel:fulcrum:backend - has access to (imports) the urn:org:netkernel:ext:introspect space.
We are going to proof the above by making our res:/introduction/helloworld-xxxxx resources available to the FEF.

We could just as well do it on the BEF, go ahead and try that as an exercise if you like !

The FEF lives in [installationdirectory]/modules/urn.org.netkernel.fulcrum.frontend-1.5.12. Change the module.xml file in there to import the urn:org:elbeesee:experiment:introduction space. Where ? Well, right underneath the comment :

  <!--Import application modules here-->
  <import>
    <uri>urn:org:elbeesee:experiment:introduction</uri>
  </import>

Save and try http://localhost:8080/introduction/helloworld-file in your browser.
Something went wrong. If you've been very attentive you may have noticed that the module.xml file of the FEF does not contain a <dynamic/> tag, changes to the module.xml file are not picked up. Stop and start NetKernel and try again.
Success. We have proved the concept.

However, if you're anything like me, it doesn't feel like success. Sure, it works, but that's quite a process to go through. Changing a file and stopping and starting NetKernel to deploy a resource to the FEF ? Anno Domini 2013 ? Really ? In fact, it was the process to follow in NK3. Things have changed.

You may undo your changes to FEF module.xml, stop and start NetKernel again (the introduction urls shouldn't work any longer) and then I want to draw your attention to this snippet :

  <!--Dynamic Imports-->
  <endpoint>

    <prototype>SimpleImportDiscovery</prototype>
    <grammar>active:SimpleImportDiscovery</grammar>
    <type>HTTPFulcrum</type>
  </endpoint>


What does that mean ? Well, it means that the FEF will automatically import spaces that contain a certain resource. So instead of changing the FEF, we're going to change our own module and add the following to the
urn:org:elbeesee:experiment:introduction space :

  <literal type="xml" uri="res:/etc/system/SimpleDynamicImportHook.xml">
     <connection>
       <type>HTTPFulcrum</type>
     </connection>
  </literal>

The uri and content of the resource are what the SimpleImportDiscovery endpoint expects. You can also provide the resource in any of the other forms that we have seen (a file resource is very common).

And you'll notice the introduction urls work once more.

Not only is this very convenient (and we take that for granted in this day and age), it is also a very powerful pattern that you can use for your own solutions !

This brings me to the end of this post. Before I go I'd like to make an important observation. It is very easy to forget - I know I did for quite a while - that other than the default (http://) transports can be used to trigger resource requests. There's a cron-transport. An ssh-transport. A mail-transport. And if all of these available transports don't fill your needs, it has been shown that any of the Apache Camel Components can be turned into a custom transport for NetKernel.