13.1.2 Element description

13.1.2.1 wiring

The root element.

13.1.2.2 virtualHosts

This element is optional.

This element is used in case you want your application to handle requests for different virtual hosts.

Remember that one Kauri Runtime instance usually corresponds to one application. If you have multiple applications that you want to associate with different virtual hosts, you would rather launch these as separate Kauri instances, and use other techniques such as putting an Apache httpd instance in front to distribute the requests to the different Kauri instances.

Attributes:

• default: (optional attribute) the value of this attribute should correspond with the name of one of the child virtualHost elements. If not specified, the first virtual host is used as default. The default virtual host will be used for mount's which specify no virtualHost attribute.

13.1.2.3 virtualHost

Attributes:

• name: a name for this virtual host, needs to be unique. This name is used for internal referencing within the wiring.xml.
• hostScheme: (optional) a regular expression matching the scheme (example: http). Defaul tis ".*".
• hostDomain: (optional) a regular expression matching the domain (example: kauriproject.org). Default is ".*".
• hostPort: (optional) a regular expression matching port number (example: 8080). Default is ".*".
• canonicalUri:(required) this attribute is important in case Kauri needs to build a URI that addresses this virtual host. An example is the use of the publicUri() function in the template language: if the specified restservice is attached to a different virtual host than the one of the current request, then the publicUri() function will need to build a URI including the scheme and authority. Since the host scheme, domain and port are optional and can be specified as regular expressions, we can't derive the canonicalUri from there.

We demonstrate the use of virtual hosts and the purpose of the canonicalUri's using an example.

<runtime>
  <virtualHosts default="web">
    <virtualHost name="static" hostDomain="static.kauriproject.org" canonicalUri="http://static.kauriproject.org"/>
    <virtualHost name="web" hostDomain="www.kauriproject.org" canonicalUri="http://www.kauriproject.org"/>
  </virtualHosts>

  <modules>
    <artifact id="webmodule" ...>
      <inject-restservice name="static" ref="staticmodule:files"/>
      <mount name="myservice" path="/foo" virtualHost="web"/>
    </artifact>

    <artifact id="staticmodule" ...>
      <mount name="files" path="" virtualHost="static"/>
    </artifact>

  </modules>

</runtime>

Suppose the webmodule generates a page with a template that creates a link as follows:

<a href="${publicUri('service:/static/downloads/bar.zip')}">bar.zip</a>

The purpose of the publicUri() function is to translate the service-URI in the argument to a public URI. The "static" service of the webmodule is provided by the "files" service of the staticmodule, which is mounted on the path "" on the virtualHost static. Since the virtual host is different from the request to the webmodule, the publicUri() function will generate an absoute URI: http://static.kauriproject.org/downloads/bar.zip.

13.1.2.4 modules

The modules element is the most important part of the runtime configuration: it specifies which modules to launch, and the wiring of the services between them.

Modules can be specified in three ways: using file references, using artifact references, or by specifying a directory containing module jars.

Each module is identified by a unique id. Within the wiring.xml, this is used for describing the wiring between the modules. At runtime, it may be used for informational or error messages.

The order in which the modules are defined is important. It is in this order that the modules will be started. The wiring between the modules needs to be such that there are no forward references to modules which are not yet launched. To put it in another way, the Kauri Runtime is currently not smart enough to figure out the startup order itself.

13.1.2.5 file

Specifies a module using a file reference.

Might be useful sometimes, but in general we recommend to refer to modules as artifacts.

Attributes:

• id: a unique id for this module
• path: path to a module jar file

13.1.2.6 artifact

Specifies a module using a Maven repository reference.

Attributes:

• id: a unique id for this module
• groupId:
• artifactId:
• classifier: (optional) the classifier is an additional dimension to identify an artifact. It is not often used. Sometimes it is used for projects which provide jdk-specific artifacts.
• version: This version attribute is optional for modules which have org.kauriproject as groupId. In that case, the version of the currently running Runtime will be used as default.

13.1.2.7 directory

Using directory, you can tell the runtime to launch all the modules jars in the specified directory (non-jar files will be ignored).

The modules will be loaded in alphabetical order according to their file name.

When using directory, explicit wiring between modules and mounting of restservices is not possible.

Attributes:

• id: the actual module id's will be a combination of this id and the file name.
• path: path to the directory containing the module jars.

13.1.2.8 mount

Mounts a REST-service exported by a module on certain path of a certain virtual host, to make it available for access from outside the application.

Attributes:

• name: the name of the REST-service, as specified in the kauri:export-restservice element in the module's spring config.
• path: the path on which to mount. We recommend the following:
• to mount on the root, specify an empty path ""
• to mount on a specific path, start with slash but don't end on it: "/foo/bar"
• virtualHost: (optional) the virtual host on which to mount, if not specified the default virtual host is used.
• canonical: (optional) boolean true/false. In case the same REST-service is mounted on multiple path, this attribute can be used to define the canonical one. There should be only one mount per REST-service which has this attribute as true. If none is specified as being cannonical, the first one is assumed to be the canonical. The canonical mount is relevant for translation of internal to public links, as is done by the publicUri() function of the template language.

13.1.2.9 inject-restservice

This is used to wire a REST-service dependency of a module.

If a module's Spring config contains kauri:import-restservice elements, then you use inject-restservice to connect the restservice.

REST-service dependencies can be connected to REST-services that are exported by other modules, or to arbitrary URIs.

Attributes:

• name: the name of the REST-service, as specified in the kauri:import-restservice element in the module's Spring config.
• ref: reference to a REST-service exported by another module, or an arbitrary URL.
• other REST-service: use "module-id:restservice-name" syntax
• URL:  use "url(...)" syntax

Example:

Suppose we have two modules called module A and module B.

Module A exports (= provides) a REST-service in its Spring config:

<kauri:export-restservice name="foo" ref="beanId1"/>

Module B imports (= depends on) two REST-services in its Spring config:

<kauri:import-restservice name="bar1" ref="beanId1"/>
<kauri:import-restservice name="bar2" ref="beanId2"/>

Now, let us connect the "bar1" dependency of module B to the "foo" service provided by module A. The "bar2" dependency will be connected to an arbitrary URL.

<runtime>
  <modules>
    <artifact id="moduleA" groupId="mygroup" artifactId="artifactA" version="1.0"/>

    <artifact id="moduleB" groupId="mygroup" artifactId="artifactB" version="1.0">
      <inject-restservice name="bar1" ref="moduleA:foo"/>
      <inject-restservice name="bar2" ref="url(http://myservice.org/something/)"/>
    </artifact>
  </modules>
</runtime>

Note that the order of the modules is important: in the ref attribute you can only refer to modules that come before the current one.

13.1.2.9.1 About REST-service types

It is possible to declare a type attribute on the kauri:import-restservice and kauri:export-restservice elements. This is optional, but if it is declared on both the import and export of two wired services, then these types need to be equal or an error will be given. The REST-service type is just a free-form string.

13.1.2.10 inject-javaservice

This is used to wire a Java-service dependency of a module.

Note that wiring Java services is optional. Since Java services are typed, the Runtime can auto-wire dependencies on a certain type of Java service as long as there is only one provided service for that type.

Attributes:

• The service to wire can be identified by using one of the following attributes (not both):
• name: the name of the Java-service, as specified in the kauri:import-service element in the module's Spring config.
• service: the type of the Java-service
• ref: use "module-id:javaservice-name" syntax

When performing the wiring for a particular dependency, the Runtime will first see if there is an inject for this particular dependency, identified by name. If that is not the case, it will look if there is an inject for the type of service. If that is not the case, the Runtime will auto-wire the dependency by looking in the global Java service registry for a service of that type. If there would be more than one available, or none, an error will be thrown.