WARNING: This server provides a static reference view of the NetKernel documentation. Links to dynamic content do not work. For the best experience we recommend you install NetKernel and view the documentation in the live system .

Endpoint
Name:WebMapperOverlay
Description:Translate location of web content
Id:mod.architecture.WebMapper
Category:overlay

WebMapperOverlay is an overlay. You must instantiate an instance of the overlay from its prototype, this will create a new instance within your application space.

Parameters

The mod.architecture.WebMapper prototype has the following initialisation parameters:

NameRulesTypingDefaultDescription
spaceMandatorySpace(none)
A nested space definition which the overlay will delegate all requests in to.
configMandatoryIdentifier or XML(none)
configuration of overlay

Here is an auto-generated example of how to instantiate an instance of WebMapperOverlay:

<overlay>
  <prototype>mod.architecture.WebMapper</prototype>
  <config>configuration of overlay</config>
  <space>
    < !--wrapped space...-->
  </space>
</overlay>
Import Requirements

To use WebMapperOverlay overlay you must import the module urn:com:ten60:netkernel:mod:architecture:

<import>
  <uri>urn:com:ten60:netkernel:mod:architecture</uri>
</import>

Operation

This overlay takes web content from inside the overlay and maps it to a different path on the outside of the overlay. The web content may come from local resources or it may come from another server and this instance acts as a proxy.

This overlay not only maps the resource identifiers exposed but actively translates the responses from various common web representations - XHTML, HTML, Javascript and CSS - by looking for embedded URIs and translating them as necessary to preserve the integrity of the web content. Only responses from SOURCE requests are translated and all other verbs are passed through transparently.

XHTML / HTML translation

If the response from a request passing through the overlay has a mime type of "text/html" or "application/xhtml+xml" the response is interrogated for URIs that may require translation. If HTML cannot be parsed as XML then tagSoup is used to convert to XML. In this scenario you will need to import the Web Core module:

<import>
  <uri>urn:org:netkernel:web:core</uri>
</import>

Then identifiers found in the following XPath locations are translated:

  • //script/@src
  • //link/@href
  • //a/@href
  • //img/@src
  • //div/@style

With style attributes only identifiers contained within the url() construct are translated.

CSS translation

When the response has mime type of "text/css" each rule with the stylesheet is searched for url() constructs which are then translated.

Javascript translation

When the response has a mime type of "application/x-javascript", "application/javascript" or "text/javascript" the response is processed as Javascript. Javascript documents are quite hard to translate firstly because parsing javascript is non trivial but mainly because the possible ways to express URIs within the language are almost infinite in variability when they are dynamically constructed. To constrain the problem only string sequences which fully match the internal path are translated. This is useful when you control the content of an internal web app but is less useful as a general web proxy when string sequences that might need translation are relative.

A pattern that works well is to define a global variable called baseURL and offset all server requests with this:

var baseURL="/org/netkernel/demo/webmapper/demoapp/";

$(function()
{   $("#toload").load(baseURL+"content.xml");
});

Configuration

The configuration document consists of one or more rewrite rules. Each rewrite consists of an external and an internal URI.

The external URI defines the base identifier of resources which the overlay will expose. The scheme on the external URI is ignored as the overlay allows all schemes to pass.

The internal URI defines the base identifier of resources that will be requested. If these URI isn't absolute then the scheme of the incoming request is relayed otherwise the scheme on this internal URI is used.

Semantics of URI translation

For each of the supported content types the contained URIs are translated the same way according to the semantics documented here:

  • If the link to be translated is not absolute it is absolutized against the containing document
  • For each rewrite defined in the web mapper we test to see if link to be translated base matches (including scheme, host and port if specified) the internal URI
  • For matching links we replace the existing base identifier with a new base as specified in the external URI
  • Links that match none of the rewrites are left unchanged.

Limitations

  • Javascript conversions very limited
  • for relative URIs on same host as an internal URI but not included because their path: they will not be absolutized against containing document and so will remain relative and become incorrect
  • because of NetKernels bridging of external HTTP requests query/post parameters and other HTTP specific headers will be lost unless additional work is done when actings as a transparent proxy

Examples

This example will act as a proxy for the BBC news website, exposing it on the frontend fulcrum at the address: http://localhost:8080/bbcnews/

<rootspace name="BBC proxy web mapper demo">
  <literal uri="res:/etc/system/SimpleDynamicImportHook.xml" type="xml">
    <connection>
      <type>HTTPFulcrum</type>
    </connection>
  </literal>
  <overlay>
    <prototype>mod.architecture.WebMapper</prototype>
    <config>
      <rewrite>
        <external>/bbcnews/</external>
        <internal>http://bbc.co.uk/news/</internal>
      </rewrite>
      <rewrite>
        <external>/bbcnewsimg/</external>
        <internal>http://news.bbcimg.co.uk/</internal>
      </rewrite>
    </config>
    <space>
      < !-- provide resolution to external HTTP resources-->
      <import>
        <uri>urn:org:netkernel:client:http</uri>
      </import>
      < !-- provide tagSoup to convert HTML to XML -->
      <import>
        <uri>urn:org:netkernel:web:core</uri>
      </import>
    </space>
  </overlay>
  < !-- provide Web Mapper -->
  <import>
    <uri>urn:com:ten60:netkernel:mod:architecture</uri>
    <private />
  </import>
</rootspace>

This example shows how the web mapper overlay can translate the location of a web app written using a hard coded location:

<rootspace name="Web App rewrite demo">
  <literal uri="res:/etc/system/SimpleDynamicImportHook.xml" type="xml">
    <connection>
      <type>HTTPFulcrum</type>
    </connection>
  </literal>
  <overlay>
    <prototype>mod.architecture.WebMapper</prototype>
    <config>
      < !-- relocate web app to be hosted at /location1/ -->
      <rewrite>
        <external>/location1/</external>
        <internal>/org/netkernel/demo/webmapper/demoapp/</internal>
      </rewrite>
    </config>
    <space>
      < !-- import our application -->
      <import>
        <uri>urn:org:netkernel:demo:webmapper:demoapp</uri>
      </import>
    </space>
  </overlay>
  < !-- provide Web Mapper -->
  <import>
    <uri>urn:com:ten60:netkernel:mod:architecture</uri>
    <private />
  </import>
</rootspace>