<commit_before>= User Manual
<NAME>, mail (AT) rolandkrueger dot info
v1.0, 2017-02-08
:source-highlighter: coderay
:toc:

== Introduction

This Vaadin add-on enhances the standard Vaadin Navigator component with a sophisticated interpreter for URI fragments. Using this add-on, you can design the URI fragments used by your application in an arbitrarily complex hierarchy. Furthermore, your URI fragments can contain any number of parameter values which will be interpreted and converted automatically so that these values can be handled in a type-safe way.

For example, it is possible to use URI fragments like in the following example:

....
#!/home
#!/admin/settings
#!/admin/users
#!/admin/users/id/4711/showHistory/startDate/2017-01-01/endDate/2017-01-31
#!/admin/users/id/4711/profile/activeTabsheet/address
....

As you can see, these URI fragments form a hierarchy where each individual path element can have an arbitrary number of parameters.

== Library uri-fragment-routing

The basis for this feature is established by the library https://github.com/rolandkrueger/uri-fragment-routing[uri-fragment-routing]. This library is responsible for  the URI fragment interpretation process, the extraction and conversion of parameter values and the management of the URI fragment hierarchy.

This Vaadin add-on simply consists of a single wrapper class around a common Vaadin `Navigator` and the boilerplate code to make the URI fragment interpretation process of library `uri-fragment-routing` available for Vaadin applications.
  
This library uses a different approach for interpreting URI fragments than the standard Vaadin `Navigator`. While the `Navigator` tries to extract a view name from the URI fragment, the `uri-fragment-routing` library interprets a URI fragment completely and tries to resolve it into an _action command class_. If such a class could be found for a given URI fragment, it is instantiated and executed. Thus, this library uses the _Command Design Pattern_, while the hierarchical URI fragments are interpreted using the _Chain of Responsibility Design Pattern_.

For details about the correct usage of the library `uri-fragment-routing`, please consult the documentation provided on the library's https://github.com/rolandkrueger/uri-fragment-routing[project page].

== How to Use the Add-on

To include the add-on in your project, you only need to add a new dependency on the add-on in your build configuration. For Maven, this would be:

....
<dependency>
    <groupId>org.vaadin.addons.uriactions</groupId>
    <artifactId>uri-fragment-actions-for-vaadin</artifactId>
    <version>1.0.0</version>
</dependency>
....

Adapt the version accordingly.

The add-on consists only of two classes one of which is the important one: `UriFragmentActionNavigatorWrapper`. This class is a wrapper around a standard Vaadin https://vaadin.com/docs/-/part/framework/advanced/advanced-navigator.html[Navigator]. This wrapper enhances the navigator with additional functionality, namely the option to resolve parameterized URI fragments to action command objects. The navigator wrapper determines the action command which is responsible for a given URI fragment, instantiates an object of this action command, and executes this subsequently.

Class `UriFragmentActionNavigatorWrapper` offers the same constructors as class `Navigator`. This means that you can add a custom `ViewDisplay` or a `ComponentContainer` to the navigator wrapper as you can do with a common navigator.

However, the navigator wrapper additionally offers the option to pass a `UriActionMapperTree` object into it which is the basis for resolving parameterized URI fragments into action command objects. If you provide an action mapper tree, then this tree has precedence in the URI fragment interpretation process. That is, it is first attempted to resolve a URI fragment using the action mapper tree. Only when a fragment could not be resolved with the action mapper tree, it will be handled by the built-in mechanisms of class `Navigator`.

By that, you can choose to handle simple cases with the standard Vaadin mechanism (e. g. using a `SingleComponentContainerViewDisplay` or a `ComponentContainerViewDisplay`) and complex cases with a `UriActionMapperTree`.

To do that, you can add custom view classes or `ViewProvider` objects to the wrapped navigator. You can obtain the reference of the wrapped navigator with method `getNavigator()`. The `View` and `ViewProvider` objects that you add to the wrapped navigator will be used by the navigator in the usual way. Note that you don't need to add any specific views or view providers to the wrapped navigator if you want URI fragments to be handled only by the URI action mapper tree.

=== Assembling a URI Action Mapper Tree

For detailed information about the individual features of class `UriActionMapperTree` and how to create and configure an instance of this class, please consult the `uri-fragment-routing` library's http://roklib.org/usage.html[user manual].

A `UriActionMapperTree` is thread-safe and can be shared by all `UI` objects. It is therefore important that the action mapper tree object is created with application-scope (e. g. as a static singleton or using an application-scoped service). It should be avoided to create this instance in the `init()`-method of your application's `UI` class. This would unnecessarily waste a lot of memory.

When you have created a `UriActionMapperTree` object, you can pass it to the navigator wrapper with `setUriActionMapperTree()`. We will look at a simple example where we want to build an action mapper tree which is able to handle the following URI fragments:

....
#!user
#!user/profile
#!admin
#!admin/users
#!admin/groups
#!settings
....

This can be achieved with the following code. Note that in this simple example, the URI action mapper tree is stored in a static variable.

[source,java]
----
public class MyUI extends UI {
<commit_msg>Add remark about access control<commit_after>= User Manual
<NAME>, mail (AT) rolandkrueger dot info
v1.0, 2017-02-08
:source-highlighter: coderay
:toc:

== Introduction

This Vaadin add-on enhances the standard Vaadin Navigator component with a sophisticated interpreter for URI fragments. Using this add-on, you can design the URI fragments used by your application in an arbitrarily complex hierarchy. Furthermore, your URI fragments can contain any number of parameter values which will be interpreted and converted automatically so that these values can be handled in a type-safe way.

For example, it is possible to use URI fragments like in the following example:

....
#!/home
#!/admin/settings
#!/admin/users
#!/admin/users/id/4711/showHistory/startDate/2017-01-01/endDate/2017-01-31
#!/admin/users/id/4711/profile/activeTabsheet/address
....

As you can see, these URI fragments form a hierarchy where each individual path element can have an arbitrary number of parameters.

== Library uri-fragment-routing

The basis for this feature is established by the library https://github.com/rolandkrueger/uri-fragment-routing[uri-fragment-routing]. This library is responsible for  the URI fragment interpretation process, the extraction and conversion of parameter values and the management of the URI fragment hierarchy.

This Vaadin add-on simply consists of a single wrapper class around a common Vaadin `Navigator` and the boilerplate code to make the URI fragment interpretation process of library `uri-fragment-routing` available for Vaadin applications.
  
This library uses a different approach for interpreting URI fragments than the standard Vaadin `Navigator`. While the `Navigator` tries to extract a view name from the URI fragment, the `uri-fragment-routing` library interprets a URI fragment completely and tries to resolve it into an _action command class_. If such a class could be found for a given URI fragment, it is instantiated and executed. Thus, this library uses the _Command Design Pattern_, while the hierarchical URI fragments are interpreted using the _Chain of Responsibility Design Pattern_.

For details about the correct usage of the library `uri-fragment-routing`, please consult the documentation provided on the library's https://github.com/rolandkrueger/uri-fragment-routing[project page].

== How to Use the Add-on

To include the add-on in your project, you only need to add a new dependency on the add-on in your build configuration. For Maven, this would be:

....
<dependency>
    <groupId>org.vaadin.addons.uriactions</groupId>
    <artifactId>uri-fragment-actions-for-vaadin</artifactId>
    <version>1.0.0</version>
</dependency>
....

Adapt the version accordingly.

The add-on consists only of two classes one of which is the important one: `UriFragmentActionNavigatorWrapper`. This class is a wrapper around a standard Vaadin https://vaadin.com/docs/-/part/framework/advanced/advanced-navigator.html[Navigator]. This wrapper enhances the navigator with additional functionality, namely the option to resolve parameterized URI fragments to action command objects. The navigator wrapper determines the action command which is responsible for a given URI fragment, instantiates an object of this action command, and executes this subsequently.

Class `UriFragmentActionNavigatorWrapper` offers the same constructors as class `Navigator`. This means that you can add a custom `ViewDisplay` or a `ComponentContainer` to the navigator wrapper as you can do with a common navigator.

However, the navigator wrapper additionally offers the option to pass a `UriActionMapperTree` object into it which is the basis for resolving parameterized URI fragments into action command objects. If you provide an action mapper tree, then this tree has precedence in the URI fragment interpretation process. That is, it is first attempted to resolve a URI fragment using the action mapper tree. Only when a fragment could not be resolved with the action mapper tree, it will be handled by the built-in mechanisms of class `Navigator`.

By that, you can choose to handle simple cases with the standard Vaadin mechanism (e. g. using a `SingleComponentContainerViewDisplay` or a `ComponentContainerViewDisplay`) and complex cases with a `UriActionMapperTree`.

To do that, you can add custom view classes or `ViewProvider` objects to the wrapped navigator. You can obtain the reference of the wrapped navigator with method `getNavigator()`. The `View` and `ViewProvider` objects that you add to the wrapped navigator will be used by the navigator in the usual way. Note that you don't need to add any specific views or view providers to the wrapped navigator if you want URI fragments to be handled only by the URI action mapper tree.

=== Assembling a URI Action Mapper Tree

For detailed information about the individual features of class `UriActionMapperTree` and how to create and configure an instance of this class, please consult the `uri-fragment-routing` library's http://roklib.org/usage.html[user manual].

A `UriActionMapperTree` is thread-safe and can be shared by all `UI` objects. It is therefore important that the action mapper tree object is created with application-scope (e. g. as a static singleton or using an application-scoped service). It should be avoided to create this instance in the `init()`-method of your application's `UI` class. This would unnecessarily waste a lot of memory. A consequence of this is that this application-scoped URI action mapper tree needs to be configured in such a way that it can handle any valid URI fragment of an application. Access control needs to be implemented either on the level of the action commands or on the service layer.

When you have created a `UriActionMapperTree` object, you can pass it to the navigator wrapper with `setUriActionMapperTree()`. We will look at a simple example where we want to build an action mapper tree which is able to handle the following URI fragments:

....
#!user
#!user/profile
#!admin
#!admin/users
#!admin/groups
#!settings
....

This can be achieved with the following code. Note that in this simple example, the URI action mapper tree is stored in a static variable.

[source,java]
----
public class MyUI extends UI {

{'fraction_non_alphanumeric': 0.05676605504587156, 'fraction_numerical': 0.006061598951507209, 'mean_word_length': 4.748116760828625, 'pattern_counts': {'":': 0, '<': 21, '<?xml version=': 0, '>': 21, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7364137', 'n_tokens_mistral': 3013, 'n_tokens_neox': 2874, 'n_words': 1674}