Fix #1

Fix #1

[[_constraints_validator]]
= Validator

.Purpose
Adds custom validation to a field.

[source,java,options="nowrap"]
.Java
----
.e("even", list(validator( (Number v) -> {val % 2 ? "" : "validator.invalid"} )))
.e("password2", list(validator( (Number v, Bean b) -> areEqual(b.password, val) ? "" : "passwords.do.not.match" )))
----

[source,groovy,options="nowrap"]
.Groovy
----
even(validator: { val -> val % 2 ? '' : 'validator.invalid' })
password2(validator: { v, obj -> obj.password == val ? '' : 'passwords.do.not.match' })
----

.Description

A custom validator is implemented by a Closure that takes up to two parameters. If the Closure accepts zero or
one parameter, the parameter value will be the one being validated ("it" in the case of a zero-parameter Closure).
If it accepts two parameters the first is the value and the second is the class instance being validated.
This is useful when your validation needs access to other fields, for example when checking that two entered
passwords are the same.

The closure can return:

 * null or empty String to indicate that the value is valid.
 * a String to indicate the error code to append to the "classname.propertyName." String used to resolve the
   error message. If a field-specific message cannot be resolved, the error code itself will be resolved allowing
   for global error messages.

.Messages
For property validator
[horizontal]
Error Codes:: `className.propertyName.validator.invalid`, `default.invalid.property.validator.message`
Template:: Property [{0}] of class [{1}] with value [{2}] is invalid

For Object validator
[horizontal]
Error Codes:: `className.propertyName.validator.invalid`, `default.invalid.object.validator.message`
Template:: Property [{0}] of class [{1}] with value [{2}] is invalid

[[_constraints_validator]]
= Validator

.Purpose
Adds custom validation to a field.

[source,java,options="nowrap"]
.Java
----
.e("even", list(validator( (Number v) -> {val % 2 ? "" : "validator.invalid"} )))
.e("password2", list(validator( (Number v, Bean b) -> areEqual(b.password, val) ? "" : "passwords.do.not.match" )))
----

[source,groovy,options="nowrap"]
.Groovy
----
even(validator{ val -> val % 2 ? '' : 'validator.invalid' })
password2(validator{ v, obj -> obj.password == val ? '' : 'passwords.do.not.match' })
----

.Description

A custom validator is implemented by a Closure that takes up to two parameters. If the Closure accepts zero or
one parameter, the parameter value will be the one being validated ("it" in the case of a zero-parameter Closure).
If it accepts two parameters the first is the value and the second is the class instance being validated.
This is useful when your validation needs access to other fields, for example when checking that two entered
passwords are the same.

The closure can return:

 * null or empty String to indicate that the value is valid.
 * a String to indicate the error code to append to the "classname.propertyName." String used to resolve the
   error message. If a field-specific message cannot be resolved, the error code itself will be resolved allowing
   for global error messages.

.Messages
For property validator
[horizontal]
Error Codes:: `className.propertyName.validator.invalid`, `default.invalid.property.validator.message`
Template:: Property [{0}] of class [{1}] with value [{2}] is invalid

For Object validator
[horizontal]
Error Codes:: `className.propertyName.validator.invalid`, `default.invalid.object.validator.message`
Template:: Property [{0}] of class [{1}] with value [{2}] is invalid


Update 2017-04-30-Reboot.adoc

Update 2017-04-30-Reboot.adoc

= Reboot
:published_at: 2017-04-30
:hp-tags: Blog, Open_Source,

[quote]
____
I amar prestar aen, +
Han mathon ne nen, +
Han mathon ne chae +
A han noston ned 'wilith
____

And again, my world is changing. A bit more than one year ago, I moved from a self-hosted blog built with https://ghost.org/[Ghost] to a fully managed website using Jimdo's website construction kit. Sure, the effort for maintaining the full stack (server, os, database, web server software, etc.) has gone, and I certainly don't want it back.

But maintaining the website itself has proven to be a bit of a hassle with Jimdo -- each page, even each blog post, has to be bricolaged together with predefined content elements. So a lot of my time spent on the website went into layouting articles, instead of writing content. Other than with Ghost, you couldn't just log in and write away in simple plain text (https://en.wikipedia.org/wiki/Markdown[Markdown], to be precise).

This really had an impact on my posting frequency -- at some time, it was as low as just once every couple of months (my personal "best" was a full 5 months of silence). Not being happy with Jimdo (mostly due to that), I constantly kept looking for alternate solutions, that would give me back an easier content creation, but not at the cost of making me spend hours on administrating servers and applications again.

I tried some big CMS stuff (like https://plone.org/[Plone 5], https://www.django-cms.org/[django CMS], http://www.opencms.org/[OpenCms] and http://www.ametys.org/[Ametys]) hosted on managed cloud services, but again I didn't find the simplicity I was hoping for. Either it was very complex to set up the site itself, or blogging in general was not well supported. Or media management proved to be complex, or inserting syntax-highlighted code snippets into articles was impossible without bigger hacks... just chose, none of them had real simplicity and elegance in store.

Over time, again and again I was drawn to static site generators. For some time, my blog was running on https://getnikola.com/[Nikola], and back then I had good reasons to stop using it -- mostly the long run time to get my site updated after having changed something small as a typo fix in an article, but also the fact I had to have access to a computer with the repo cloned locally and all the software dependencies installed.

Yet the simplicity of hosting a static site is still very attractive, so how on earth could I get a static blog without need for local software and build tools, and with the ability to generate content from any computer? I knew about https://pages.github.com/[GitHub Pages] and https://jekyllrb.com/[Jekyll], but I could never warm to  Jekyll or derivated static site generators (I'm simply not a ruby guy...). I also experimented with http://www.sphinx-doc.org/[Sphinx] and https://github.com/syntaf/travis-sphinx[travis-sphinx], but Sphinx is not really made for websites and blogging.

When I recently stumbled accross http://hubpress.io/[HubPress], I knew I had found what I was looking for. This blogging solution is built around GitHub pages, works fine even without ever loading something to the local computer, and offers a Ghost-like browser-based post editor (using http://asciidoctor.org/[AsciiDoc] instead of Markdown). On top, posts can be written via GitHub's built-in editor, or offline with any text editor -- they're just `.adoc` files in a GitHub pages repository or branch.

After more than 15 years of running a personal website, I'm certainly not naive when it comes to site generators and blogging solutions. I'm not sure HubPress will become a sustainable solution, driving my site for a longer period. However, it certainly has the potential to do so, as it brings along all the ingredients I was long looking for -- I will certainly give it the chance to prove it can do this for me, and hopefully also increase my posting frequency.

= Reboot
// :published_at: 2017-04-30
:hp-tags: Blog, Open_Source,

[quote]
____
I amar prestar aen, +
Han mathon ne nen, +
Han mathon ne chae +
A han noston ned 'wilith
____

And again, my world is changing. A bit more than one year ago, I moved from a self-hosted blog built with https://ghost.org/[Ghost] to a fully managed website using Jimdo's website construction kit. Sure, the effort for maintaining the full stack (server, os, database, web server software, etc.) has gone, and I certainly don't want it back.

But maintaining the website itself has proven to be a bit of a hassle with Jimdo -- each page, even each blog post, has to be bricolaged together with predefined content elements. So a lot of my time spent on the website went into layouting articles, instead of writing content. Other than with Ghost, you couldn't just log in and write away in simple plain text (https://en.wikipedia.org/wiki/Markdown[Markdown], to be precise).

This really had an impact on my posting frequency -- at some time, it was as low as just once every couple of months (my personal "best" was a full 5 months of silence). Not being happy with Jimdo (mostly due to that), I constantly kept looking for alternate solutions, that would give me back an easier content creation, but not at the cost of making me spend hours on administrating servers and applications again.

I tried some big CMS stuff (like https://plone.org/[Plone 5], https://www.django-cms.org/[django CMS], http://www.opencms.org/[OpenCms] and http://www.ametys.org/[Ametys]) hosted on managed cloud services, but again I didn't find the simplicity I was hoping for. Either it was very complex to set up the site itself, or blogging in general was not well supported. Or media management proved to be complex, or inserting syntax-highlighted code snippets into articles was impossible without bigger hacks... just chose, none of them had real simplicity and elegance in store.

Over time, again and again I was drawn to static site generators. For some time, my blog was running on https://getnikola.com/[Nikola], and back then I had good reasons to stop using it -- mostly the long run time to get my site updated after having changed something small as a typo fix in an article, but also the fact I had to have access to a computer with the repo cloned locally and all the software dependencies installed.

Yet the simplicity of hosting a static site is still very attractive, so how on earth could I get a static blog without need for local software and build tools, and with the ability to generate content from any computer? I knew about https://pages.github.com/[GitHub Pages] and https://jekyllrb.com/[Jekyll], but I could never warm to  Jekyll or derivated static site generators (I'm simply not a ruby guy...). I also experimented with http://www.sphinx-doc.org/[Sphinx] and https://github.com/syntaf/travis-sphinx[travis-sphinx], but Sphinx is not really made for websites and blogging.

When I recently stumbled accross http://hubpress.io/[HubPress], I knew I had found what I was looking for. This blogging solution is built around GitHub pages, works fine even without ever loading something to the local computer, and offers a Ghost-like browser-based post editor (using http://asciidoctor.org/[AsciiDoc] instead of Markdown). On top, posts can be written via GitHub's built-in editor, or offline with any text editor -- they're just `.adoc` files in a GitHub pages repository or branch.

After more than 15 years of running a personal website, I'm certainly not naive when it comes to site generators and blogging solutions. I'm not sure HubPress will become a sustainable solution, driving my site for a longer period. However, it certainly has the potential to do so, as it brings along all the ingredients I was long looking for -- I will certainly give it the chance to prove it can do this for me, and hopefully also increase my posting frequency.


Remove mention of removed API (#8701)

Remove mention of removed API (#8701)

Deprecated setColumns was removed in fd3617b

---
title: NativeSelect
order: 18
layout: page
---

[[components.nativeselect]]
= NativeSelect

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/drop-down-menu"]
endif::web[]

[classname]#NativeSelect# is a selection component allows selecting an item from a
drop-down list. It is implemented with the native selection input of web browsers, using the HTML [literal]#++<select>++# element.

[source, java]
----
// Create the selection component
NativeSelect<String> select =
    new NativeSelect<>("Native Selection");

// Add some items
select.setItems("Mercury", "Venus", ...);
----

[[figure.components.nativeselect.basic]]
.The [classname]#NativeSelect# Component
image::img/nativeselect-basic.png[width=20%, scaledwidth=35%]

Common selection component features are described in
<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>.

== CSS Style Rules

[source, css]
----
.v-select {}
  .v-select-select {}
----

The component has a [literal]#++v-select++# overall style. The native
[literal]#++select++# element has [literal]#++v-select-select++# style.

---
title: NativeSelect
order: 18
layout: page
---

[[components.nativeselect]]
= NativeSelect

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/drop-down-menu"]
endif::web[]

[classname]#NativeSelect# is a selection component allows selecting an item from a
drop-down list. It is implemented with the native selection input of web browsers, using the HTML [literal]#++<select>++# element.

[source, java]
----
// Create the selection component
NativeSelect<String> select =
    new NativeSelect<>("Native Selection");

// Add some items
select.setItems("Mercury", "Venus", ...);
----

The [methodname]#setColumns()# allows setting the width of the list as
"columns", which is a measure that depends on the browser.

[[figure.components.nativeselect.basic]]
.The [classname]#NativeSelect# Component
image::img/nativeselect-basic.png[width=20%, scaledwidth=35%]

Common selection component features are described in
<<dummy/../../../framework/components/components-selection#components.selection,"Selection Components">>.

== CSS Style Rules

[source, css]
----
.v-select {}
  .v-select-select {}
----

The component has a [literal]#++v-select++# overall style. The native
[literal]#++select++# element has [literal]#++v-select-select++# style.


Update 2016-02-29-multithreading.adoc

Update 2016-02-29-multithreading.adoc

= multithreading

== threads, groups
----
void change_count(){]

boost::thread_group threads;
for (int i=0; i < num_threads; ++i)
   threads.create_thread(&change_count);

   threads.join_all();
}
----

== synchronization (locks)

* locks guard (RAII, inutile d'appeler lock/unlock)

[source,c++]
----
for (int i = 0; i < 5; ++i)
{
  wait(1);
  boost::lock_guard<boost::mutex> lock{mutex};
  std::cout << "Thread " << get_id() << ": " << i << std::endl;
}
----

* shared_mutex (lock par shared_lock ou unique lock)

[source,c++]
----
void write_acess()
{
  boost::unique_lock<boost::mutex> lock{mutex};
}

void read_accesst()
{
  for (int i = 0; i < 3; ++i)
  {
    boost::shared_lock<boost::shared_mutex> lock{mutex};
    std::cout << random_numbers.back() << '\n';
  }
}
----

== conditions

[source,c++]
----
std::condition_variable cv;
std::mutex cv_m; // This mutex is used for three purposes:
                 // 1) to synchronize accesses to i
                 // 2) to synchronize accesses to std::cerr
                 // 3) for the condition variable cv
int i = 0;

void waits()
{
    std::unique_lock<std::mutex> lk(cv_m);
    std::cerr << "Waiting... \n";
    cv.wait(lk, []{return i == 1;});
    std::cerr << "...finished waiting. i == 1\n";
}

void signals()
{
    {
        std::lock_guard<std::mutex> lk(cv_m);
        i = 1;
        std::cerr << "Notifying again...\n";
    }
    cv.notify_all();
}
----

*Tous* les threads qui exécutent waits vont être débloqués par le notify_all
Le mutex est utilisé par le thread signalant lorsqu'il touche à la condition
Il est aussi utilisé par le thread en attente.

IMPORTANT: Il est unlocké au début de l'appel de la fonction wait

== future, promise

* version complète
On peut faire un get sur un futur
On fait un set sur une promise

On peut récupérer le futur associée d'une promise

[source,c++]
----
void accumulate(boost::promise<int> &p)
{
  int sum = 0;
  for (int i = 0; i < 5; ++i)
    sum += i;
  p.set_value(sum);
}

int main()
{
  boost::promise<int> p;
  boost::future<int> f = p.get_future();
  boost::thread t{accumulate, std::ref(p)};
  std::cout << f.get() << '\n';
}
----

* version simplifiée (avec async)

[source,c++]
----
int accumulate()
{
  int sum = 0;
  for (int i = 0; i < 5; ++i)
    sum += i;
  return sum;
}

int main()
{
  boost::future<int> f = boost::async(accumulate);
  std::cout << f.get() << '\n';
}
----

= multithreading

== threads, groups
----
void change_count(){]

boost::thread_group threads;
for (int i=0; i < num_threads; ++i)
   threads.create_thread(&change_count);

   threads.join_all();
}
----

== synchronization (locks)

* locks guard (RAII, inutile d'appeler lock/unlock)

[source,c++]
----
for (int i = 0; i < 5; ++i)
{
  wait(1);
  boost::lock_guard<boost::mutex> lock{mutex};
  std::cout << "Thread " << get_id() << ": " << i << std::endl;
}

* shared_mutex (lock par shared_lock ou unique lock)
----

[source,c++]
----
void write_acess()
{
  boost::unique_lock<boost::mutex> lock{mutex};
}

void read_accesst()
{
  for (int i = 0; i < 3; ++i)
  {
    boost::shared_lock<boost::shared_mutex> lock{mutex};
    std::cout << random_numbers.back() << '\n';
  }
}
----

== conditions

[source,c++]
----
std::condition_variable cv;
std::mutex cv_m; // This mutex is used for three purposes:
                 // 1) to synchronize accesses to i
                 // 2) to synchronize accesses to std::cerr
                 // 3) for the condition variable cv
int i = 0;

void waits()
{
    std::unique_lock<std::mutex> lk(cv_m);
    std::cerr << "Waiting... \n";
    cv.wait(lk, []{return i == 1;});
    std::cerr << "...finished waiting. i == 1\n";
}

void signals()
{
    {
        std::lock_guard<std::mutex> lk(cv_m);
        i = 1;
        std::cerr << "Notifying again...\n";
    }
    cv.notify_all();
}
----

*Tous* les threads qui exécutent waits vont être débloqués par le notify_all
Le mutex est utilisé par le thread signalant lorsqu'il touche à la condition
Il est aussi utilisé par le thread en attente.

IMPORTANT: Il est unlocké au début de l'appel de la fonction wait

== future, promise

* version complète
On peut faire un get sur un futur
On fait un set sur une promise

On peut récupérer le futur associée d'une promise

----
void accumulate(boost::promise<int> &p)
{
  int sum = 0;
  for (int i = 0; i < 5; ++i)
    sum += i;
  p.set_value(sum);
}

int main()
{
  boost::promise<int> p;
  boost::future<int> f = p.get_future();
  boost::thread t{accumulate, std::ref(p)};
  std::cout << f.get() << '\n';
}
----

* version simplifiée (avec async)
----
int accumulate()
{
  int sum = 0;
  for (int i = 0; i < 5; ++i)
    sum += i;
  return sum;
}

int main()
{
  boost::future<int> f = boost::async(accumulate);
  std::cout << f.get() << '\n';
}
----


Update 2017-06-18-Vuex-Quick-Ref.adoc

Update 2017-06-18-Vuex-Quick-Ref.adoc

// = Your Blog title
// See https://hubpress.gitbooks.io/hubpress-knowledgebase/content/ for information about the parameters.
// :hp-image: /covers/cover.png
// :published_at: 2019-01-31
// :hp-tags: HubPress, Blog, Open_Source,
// :hp-alt-title: My English Title

= Vuex Quick Ref
:published_at: 2017-06-18
:hp-tags: JavaScricpt, vuejs, vuex

## Store

- Instanciated with ```Vuex.Store(options)``` constructor
- Injected into child components as ```this.$store``` to enable easy access
- Properties of ```options``` object are described below.

### state

- ```state``` is the reactive data stored into a vuex ```store``` and very similar to the ```data``` property in options for component constructor.
- ```state``` variables are usually exposed as ```computed``` properties to enable easy access within components.
- ```mapState```
    - A utility function to mix & expose ```state``` variables as ```computed``` properties in components.
    - Imported as ```import { mapState } from 'vuex'```
    - Returns object, so it can be used to merge with local ```computed``` properties of components using [object spread](#) syntax,  i.e. ```...mapState({})```

### getters

- ```getters``` is for vuex ```store``` what ```computed``` is for components.
- ```getters``` are also exposed through ```computed``` properties to enable easy access within components.
- Signature of **getter** is ```getterName: function(state, getters) { /** ... */ }```
- Arguments can also be passed to getters by returning a function. This is particularly useful when querying an array in the store is required.
- ```mapGetters```
    - A utility function to mix & expose ```getters``` in ```computed``` within components.
    - Imported as ```import { mapGetters } from 'vuex'```
    - Returns object, so it can be used to merge with local ```computed``` properties of components using [object spread](#) syntax,  i.e. ```...mapGetters({})```

### mutations

- ```mutations``` is an object to define **mutator** methods in vuex ```store``` which are allowed & responsible to modify store's ```state```.
- It is not permissible to modify ```state``` directly in vuex stores, so **mutators** are needed.
- Signature of **mutator** is ```mutatorName: function(state, [payload]) { /** ... */ }```
- To invoke a **mutator**, you need to call ```store.commit(mutation, [payload])``` with its ```name``` and it's optional ```payload```.
- ```mutations``` must be synchronous.
- ```mapMutations```
    - A utility function to mix & expose ```mutations``` as component ```methods``` that invokes respective mutation via ```store.commit```.
    - Imported as ```import { mapMutations } from 'vuex'```
    - Returns object, so it can be used to merge with local ```methods``` option of components using [object spread](#) syntax,  i.e. ```...mapMutations({})```

### actions

- Actions are similar to mutations, the differences being that:
    - Instead of mutating the state, actions commit mutations.
    - Actions can contain arbitrary asynchronous operations.
- Action handlers receive a ```context``` object which exposes the same set of methods/properties on the ```store``` instance, so you can call ```context.commit``` to commit a mutation, or access the ```state``` and ```getters``` via ```context.state``` and ```context.getters``` respectively.
- Actions are triggered with the ```store.dispatch(actionName, payload)``` method.

# Vuex Quick Ref

## Store

- Instanciated with ```Vuex.Store(options)``` constructor
- Injected into child components as ```this.$store``` to enable easy access
- Properties of ```options``` object are described below.

### state

- ```state``` is the reactive data stored into a vuex ```store``` and very similar to the ```data``` property in options for component constructor.
- ```state``` variables are usually exposed as ```computed``` properties to enable easy access within components.
- ```mapState```
    - A utility function to mix & expose ```state``` variables as ```computed``` properties in components.
    - Imported as ```import { mapState } from 'vuex'```
    - Returns object, so it can be used to merge with local ```computed``` properties of components using [object spread](#) syntax,  i.e. ```...mapState({})```

### getters

- ```getters``` is for vuex ```store``` what ```computed``` is for components.
- ```getters``` are also exposed through ```computed``` properties to enable easy access within components.
- Signature of **getter** is ```getterName: function(state, getters) { /** ... */ }```
- Arguments can also be passed to getters by returning a function. This is particularly useful when querying an array in the store is required.
- ```mapGetters```
    - A utility function to mix & expose ```getters``` in ```computed``` within components.
    - Imported as ```import { mapGetters } from 'vuex'```
    - Returns object, so it can be used to merge with local ```computed``` properties of components using [object spread](#) syntax,  i.e. ```...mapGetters({})```

### mutations

- ```mutations``` is an object to define **mutator** methods in vuex ```store``` which are allowed & responsible to modify store's ```state```.
- It is not permissible to modify ```state``` directly in vuex stores, so **mutators** are needed.
- Signature of **mutator** is ```mutatorName: function(state, [payload]) { /** ... */ }```
- To invoke a **mutator**, you need to call ```store.commit(mutation, [payload])``` with its ```name``` and it's optional ```payload```.
- ```mutations``` must be synchronous.
- ```mapMutations```
    - A utility function to mix & expose ```mutations``` as component ```methods``` that invokes respective mutation via ```store.commit```.
    - Imported as ```import { mapMutations } from 'vuex'```
    - Returns object, so it can be used to merge with local ```methods``` option of components using [object spread](#) syntax,  i.e. ```...mapMutations({})```

### actions

- Actions are similar to mutations, the differences being that:
    - Instead of mutating the state, actions commit mutations.
    - Actions can contain arbitrary asynchronous operations.
- Action handlers receive a ```context``` object which exposes the same set of methods/properties on the ```store``` instance, so you can call ```context.commit``` to commit a mutation, or access the ```state``` and ```getters``` via ```context.state``` and ```context.getters``` respectively.
- Actions are triggered with the ```store.dispatch(actionName, payload)``` method.


improved docs

improved docs

== Threading and Parallelism with RxJava and Java 8

Probably you also had a difficult start concerning RxJava and threading like http://www.grahamlea.com/2014/07/rxjava-threading-examples[Graham Lea did].

I had.

Why did I? I made some false assumptions regarding threading instead of properly learning "stuff" first using e.g. http://www.pluralsight.com/courses/reactive-programming-java-8-rxjava.

The main point about Rx and parallelsim / concurrency is probably noted here http://www.introtorx.com/Content/v1.0.10621.0 and states

a) _"Rx is single-threaded by default"_

and

b) _"While Rx has concurrency features, these should not be mistaken for a concurrency framework. Rx is designed for querying data, and as discussed in the first chapter, parallel computations or composition of asynchronous methods is more appropriate for other frameworks."_

I would sum this up to:

Rx is created mainly for "clients" (client applications like apps, desktop gui applications, ...) where
you have typically one thread from the GUI and you would like to "spin off" several background tasks (in parallel) when an event like submitting a form happens,
combine these asynchronously returning background task-results to one result which you display in the GUI. It's not primarly made for "servers",
e.g. to handle concurrent HTTP requests in a webserver. But you can use it to do implement "servers", if you know "how".

See also https://github.com/ReactiveX/RxJava/issues/1673 and the section about schedulers in http://www.pluralsight.com/courses/reactive-programming-java-8-rxjava.

=== OneLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/OneLaneMcDrive.java[]

Think of a McDrive with one lane and very few customers arriving. The one lane is either free or there is one customer.
Each customer orders always the same three "things", which you can prepare with 3 workers in the background "in parallel".

* Parallelism in a logical sense
* Based on the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator (Note: @Beta annotated in RxJava 1.0.14)

In this example there is no need for backpressure, since the customers arrive "slow " and the McDrive can handle them in time.

But what happens if you increase the number of arriving customers (=decrease seconds in interval operator)?
Currently, the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator implementation in RxJava seems to "buffer" on backpressure.

=== OneLaneMcDrive2

link:../src/main/java/ch/petikoch/examples/rxjava/threading/OneLaneMcDrive2.java[]

An Implementation of OneLaneMcDrive without the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator.
Instead we use a PublishSubject instance to "communicate the result to the outside" and use an AtomicBoolean instance to limit
the number of concurrent customers to one.

You immediately understand now the "power" of the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator.

=== TwoLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/TwoLaneMcDrive.java[]

Same as OneLaneMcDrive, but now with two lanes. There are still few customers arriving concurrently. Each of the lane
is either free or there is maximum one customer in the lane. We have at each time between 0 and 2 customers concurrently.

* Parallelism in a execution sense: We can handle two customers at the same time
* Parallelism in a logical sense: like OneLaneMcDrive

There is also no need for backpressure, since the customers arrive "slow " and the McDrive can handle them in time.

=== JammedOneLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/JammedOneLaneMcDrive.java[]

Same as OneLaneMcDrive, but now with more customers arriving. The McDrive can't handle all of them "just in time",
so a wait line (queue) builds up. The longer the example runs, the longer the wait line becomes.

We need some kind of backpressure: we choose buffering (queueing) and get a "jam".

=== InfiniteLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/InfiniteLaneMcDrive.java[]

Now, we have an "infinite" number of lanes. The number of lanes grows to the point when we have
enough lanes to handle all the arriving customers "just in time".

We output the numer of lanes (=number of concurrently handled customers).

=== SingleThreadedByDefault

link:../src/main/java/ch/petikoch/examples/rxjava/threading/SingleThreadedByDefault.java[]

Let's come back from the food to the technical details. As initially said, RxJava is _"single threaded by default"_.
Although you can offload the work from one thread to an other (using Schedulers), the program flow then is switching
from one thread to another *one* thread and not to a pool of threads. Your sourcecode (e.g. your observer) is always called by
only *one* and the *same* thread.

So, to make it more clear: _"your sourcecode is always called by the same single thread"_.

Benefit? You don't have to implement thread-safe code, which is hard.

== Threading and Parallelism with RxJava and Java 8

Probably you also had a difficult start concerning RxJava and threading like http://www.grahamlea.com/2014/07/rxjava-threading-examples[Graham Lea did].

I had.

Why did I? I made some false assumptions regarding threading instead of properly learning "stuff" first using e.g. http://www.pluralsight.com/courses/reactive-programming-java-8-rxjava.

The main point about Rx and parallelsim / concurrency is probably noted here http://www.introtorx.com/Content/v1.0.10621.0 and states
a) _"Rx is single-threaded by default"_
and b) _"While Rx has concurrency features, these should not be mistaken for a concurrency framework. Rx is designed for querying data, and as discussed in the first chapter, parallel computations or composition of asynchronous methods is more appropriate for other frameworks."_

I would sum this up to:

Rx is created mainly for "clients" (client applications like apps, desktop gui applications, ...) where
you have typically one thread from the GUI and you would like to "spin off" several background tasks (in parallel) when an event like submitting a form happens,
combine these asynchronously returning background tasks results to one result which you display in the GUI. It's not primarly made for "servers",
e.g. to handle concurrent HTTP requests in a webserver. But you can use it to do implement "servers", if you know "how".

See also https://github.com/ReactiveX/RxJava/issues/1673 and the section about schedulers in http://www.pluralsight.com/courses/reactive-programming-java-8-rxjava.

=== OneLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/OneLaneMcDrive.java[]

Think of a McDrive with one lane and very few customers arriving. The one lane is either free or there is one customer.
Each customer orders always the same three "things", which you can prepare with 3 workers in the background "in parallel".

* Parallelism in a logical sense
* Based on the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator (Note: @Beta annotated in RxJava 1.0.14)

In this example there is no need for backpressure, since the customers arrive "slow " and the McDrive can handle them in time.

But what happens if you increase the number of arriving customers (=decrease seconds in interval operator)?
Currently, the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator implementation in RxJava seems to "buffer" on backpressure.

=== OneLaneMcDrive2

link:../src/main/java/ch/petikoch/examples/rxjava/threading/OneLaneMcDrive2.java[]

An Implementation of OneLaneMcDrive without the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator.
Instead we use a PublishSubject instance to "communicate the result to the outside" and use an AtomicBoolean instance to limit
the number of concurrent customers to one.

You immediately understand now the "power" of the http://reactivex.io/documentation/operators/flatmap.html[flatmap] operator.

=== TwoLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/TwoLaneMcDrive.java[]

Same as OneLaneMcDrive, but now with two lanes. There are still few customers arriving concurrently. Each of the lane
is either free or there is maximum one customer in the lane. We have at each time between 0 and 2 customers concurrently.

* Parallelism in a execution sense: We can handle two customers at the same time
* Parallelism in a logical sense: like OneLaneMcDrive

There is also no need for backpressure, since the customers arrive "slow " and the McDrive can handle them in time.

=== JammedOneLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/JammedOneLaneMcDrive.java[]

Same as OneLaneMcDrive, but now with more customers arriving. The McDrive can't handle all of them "just in time",
so a wait line (queue) builds up. The longer the example runs, the longer the wait line becomes.

We need some kind of backpressure: we choose buffering (queueing) and get a "jam".

=== InfiniteLaneMcDrive

link:../src/main/java/ch/petikoch/examples/rxjava/threading/InfiniteLaneMcDrive.java[]

Now, we have an "infinite" number of lanes. The number of lanes grows to the point when we have
enough lanes to handle all the arriving customers "just in time".

We output the numer of lanes (=number of concurrently handled customers).

=== SingleThreadedByDefault

link:../src/main/java/ch/petikoch/examples/rxjava/threading/SingleThreadedByDefault.java[]

Let's come back from the food to the technical details. As initially said, RxJava is _"single threaded by default"_.
Although you can offload the work from one thread to an other (using Schedulers), the program flow then is switching
from one thread to another *one* thread and not to a pool of threads. Your sourcecode (e.g. your observer) is always called by
only *one* and the *same* thread.

So, to make it more clear: _"your sourcecode is always called by the same single thread"_.

Benefit? You don't have to implement thread-safe code, which is hard.


Update title style. (#1364)

Update title style. (#1364)

Fixes #1349

== On the Producer Side

To start working with Spring Cloud Contract, you can add files with REST or messaging contracts expressed in either Groovy DSL or YAML to the contracts directory, which is set by the contractsDslDir property. By default, it is $rootDir/src/test/resources/contracts.

Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as the following example shows:

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-verifier</artifactId>
    <scope>test</scope>
</dependency>
```

The following listing shows how to add the plugin, which should go in the build/plugins portion of the file:

```xml
<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>${spring-cloud-contract.version}</version>
    <extensions>true</extensions>
</plugin>
```

Running `./mvnw clean install` automatically generates tests that verify the application compliance with the added contracts. By default, the tests get generated under `org.springframework.cloud.contract.verifier.tests`.

As the implementation of the functionalities described by the contracts is not yet present, the tests fail.

To make them pass, you must add the correct implementation of either handling HTTP requests or messages. Also, you must add a base test class for auto-generated tests to the project. This class is extended by all the auto-generated tests, and it should contain all the setup information necessary to run them (for example `RestAssuredMockMvc` controller setup or messaging test setup).

The following example, from pom.xml, shows how to specify the base test class:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-contract-maven-plugin</artifactId>
            <version>${spring-cloud-contract.version}</version>
            <extensions>true</extensions>
            <configuration>
                <baseClassForTests>com.example.contractTest.BaseTestClass</baseClassForTests>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
```

INFO: The baseClassForTests element lets you specify your base test class. It must be a child of a configuration element within spring-cloud-contract-maven-plugin.

Once the implementation and the test base class are in place, the tests pass, and both the application and the stub artifacts are built and installed in the local Maven repository. You can now merge the changes, and you can publish both the application and the stub artifacts in an online repository.

== On the Consumer Side

You can use Spring Cloud Contract Stub Runner in the integration tests to get a running WireMock instance or messaging route that simulates the actual service.

To do so, add the dependency to Spring Cloud Contract Stub Runner, as the following example shows:

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
    <scope>test</scope>
</dependency>
```

You can get the Producer-side stubs installed in your Maven repository in either of two ways:

By checking out the Producer side repository and adding contracts and generating the stubs by running the following commands:

```bash
$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests
```

The tests are being skipped because the producer-side contract implementation is not in place yet, so the automatically-generated contract tests fail.

By getting already-existing producer service stubs from a remote repository. To do so, pass the stub artifact IDs and artifact repository URL as Spring Cloud Contract Stub Runner properties, as the following example shows:

```yml
    stubrunner:
      ids: 'com.example:http-server-dsl:+:stubs:8080'
      repositoryRoot: https://repo.spring.io/libs-snapshot
```

Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the group-id and artifact-id values for Spring Cloud Contract Stub Runner to run the collaborators' stubs for you, as the following example shows:

```java
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
        stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {
```

Use the `REMOTE` stubsMode when downloading stubs from an online repository and `LOCAL` for offline work.

Now, in your integration test, you can receive stubbed versions of HTTP responses or messages that are expected to be emitted by the collaborator service.

== On the Producer Side

To start working with Spring Cloud Contract, you can add files with REST or messaging contracts expressed in either Groovy DSL or YAML to the contracts directory, which is set by the contractsDslDir property. By default, it is $rootDir/src/test/resources/contracts.

Then you can add the Spring Cloud Contract Verifier dependency and plugin to your build file, as the following example shows:

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-verifier</artifactId>
    <scope>test</scope>
</dependency>
```

The following listing shows how to add the plugin, which should go in the build/plugins portion of the file:

```xml
<plugin>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-contract-maven-plugin</artifactId>
    <version>${spring-cloud-contract.version}</version>
    <extensions>true</extensions>
</plugin>
```

Running `./mvnw clean install` automatically generates tests that verify the application compliance with the added contracts. By default, the tests get generated under `org.springframework.cloud.contract.verifier.tests`.

As the implementation of the functionalities described by the contracts is not yet present, the tests fail.

To make them pass, you must add the correct implementation of either handling HTTP requests or messages. Also, you must add a base test class for auto-generated tests to the project. This class is extended by all the auto-generated tests, and it should contain all the setup information necessary to run them (for example `RestAssuredMockMvc` controller setup or messaging test setup).

The following example, from pom.xml, shows how to specify the base test class:

```xml
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-contract-maven-plugin</artifactId>
            <version>${spring-cloud-contract.version}</version>
            <extensions>true</extensions>
            <configuration>
                <baseClassForTests>com.example.contractTest.BaseTestClass</baseClassForTests>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>
```

INFO: The baseClassForTests element lets you specify your base test class. It must be a child of a configuration element within spring-cloud-contract-maven-plugin.

Once the implementation and the test base class are in place, the tests pass, and both the application and the stub artifacts are built and installed in the local Maven repository. You can now merge the changes, and you can publish both the application and the stub artifacts in an online repository.
2.2. On the Consumer Side

You can use Spring Cloud Contract Stub Runner in the integration tests to get a running WireMock instance or messaging route that simulates the actual service.

To do so, add the dependency to Spring Cloud Contract Stub Runner, as the following example shows:

```xml
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-contract-stub-runner</artifactId>
    <scope>test</scope>
</dependency>
```

You can get the Producer-side stubs installed in your Maven repository in either of two ways:

By checking out the Producer side repository and adding contracts and generating the stubs by running the following commands:

```bash
$ cd local-http-server-repo
$ ./mvnw clean install -DskipTests
```

The tests are being skipped because the producer-side contract implementation is not in place yet, so the automatically-generated contract tests fail.

By getting already-existing producer service stubs from a remote repository. To do so, pass the stub artifact IDs and artifact repository URL as Spring Cloud Contract Stub Runner properties, as the following example shows:

```yml
    stubrunner:
      ids: 'com.example:http-server-dsl:+:stubs:8080'
      repositoryRoot: https://repo.spring.io/libs-snapshot
```

Now you can annotate your test class with `@AutoConfigureStubRunner`. In the annotation, provide the group-id and artifact-id values for Spring Cloud Contract Stub Runner to run the collaborators' stubs for you, as the following example shows:

```java
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment=WebEnvironment.NONE)
@AutoConfigureStubRunner(ids = {"com.example:http-server-dsl:+:stubs:6565"},
        stubsMode = StubRunnerProperties.StubsMode.LOCAL)
public class LoanApplicationServiceTests {
```

Use the `REMOTE` stubsMode when downloading stubs from an online repository and `LOCAL` for offline work.

Now, in your integration test, you can receive stubbed versions of HTTP responses or messages that are expected to be emitted by the collaborator service.


Update 2015-08-23-Define-Extrapolate.adoc

= Define Extrapolate

Extrapolate is a blog.

Not a travel blog, or a food blog, or a book/movie review blog, though these are all things that I enjoy and will likely find themselves cameos in posts here and there. Extrapolate isn't a daily/weekly/{insert regular time interval}-ly journal blog either, though it might seem like it at times.

Extrapolate is an ongoing record of the more interesting "ideas" that find their ways into my mind. I hesitate to use the word "ideas" here because (at least in my personal connotation-dictionary) __ideas__ are discrete, and useful in some compacity. The things I think about are hardly discrete and rarely useful, instead occupying the hazy intellectual territory at the intersection of personal experience and pattern recognition.

That last bit probably makes zero sense to you, so let me try to explain. As I go about my exceptionally average life, I (like my 7+ billion fellow humans) inevitably accumulate a set of experiences, memories, ideas. __These__ are discrete; I can mentally point to a conversation I've had, or an article I've read, or a place I've been to. In isolation, these "points" are hardly worth thinking about, much less writing about. If I led a more interesting life, I could've made this blog a place to simply `Ctrl+C` `Ctrl+V` these experiences/ideas from my sensory receptors, with a dash of introspection. The analytical analog of an Instagram filter, if you will.

But for better or worse, my life __is__ pretty mundane, so instead I

= Define Extrapolate

Extrapolate is a blog.

Not a travel blog, or a food blog, or a book/movie review blog, though these are all things that I enjoy and will likely find themselves cameos in posts here and there. Extrapolate isn't a daily/weekly/{insert regular time interval}-ly journal blog either, though it might seem like it at times.

Extrapolate is an ongoing record of the more interesting "ideas" that find their ways into my mind. I hesitate to use the word "ideas" here because (at least in my personal connotation-dictionary) __ideas__ are discrete, and useful in some compacity. The processes that I spend most of my mental CPU on are neither of these.


ISIS-2290: use AsciiDoc substitutions and aligned monospaced elements

[[building-apache-isis]]
= Building Apache Isis
:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or  conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
:page-partial:

== Git

The Apache Isis source code lives in a git repo.

=== Installation

The easiest place to get hold of command-line git is probably the http://git-scm.com/downloads[github download page].

On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:

image::building-apache-isis/setting-up-git.png[width="350px",link="{imagesdir}/building-apache-isis/setting-up-git.png"]

Once git is installed, the two main command line tools to note are:

* `git` command line tool
* `gitk` for viewing the commit history

If using Windows, note that github also have a dedicated https://help.github.com/articles/set-up-git[Windows client]. With a little http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx[hacking around], it can also be made to work with non-github repositories.

If using Mac, you might also want to check out Atlassian's http://www.atlassian.com/software/sourcetree/overview[Sourcetree].

==== Cloning the Apache Isis repo

First, clone the Apache Isis repo:

[source,bash]
----
git clone https://github.com/apache/isis.git
----

==== Configuring Git

Next up is to configure your user name and password:

[source,bash,subs=+quotes]
----
git config user.name "__My Name Here__"
git config user.email _myusername@apache.org_
----

Next, configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see https://git-wip-us.apache.org/[Apache's git] page:

* on Windows, use: +
+
[source,bash]
----
git config core.autocrlf true
----

* on Mac/Linux, use: +
+
[source,bash]
----
git config core.autocrlf input
----

The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.

We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:

[source,bash]
----
git config core.safecrlf true
----

Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.

Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the `[remote "origin"]` section in your `.git/config` and add the third entry shown below:

[source,bash]
----
[remote "origin"]
    url = ... whatever ...
    fetch = ... whatever ...
    fetch = +refs/tags/*:refs/tags/origin/*
----

This will ensure that a `git fetch` or `git pull` places any remote tags under `origin/xxx`.  For example, the `isis-1.0.0` tag on the origin will appear under `origin/isis-1.0.0`.

If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.

=== Getting help

Three commands of git that in particular worth knowing:

* `git help _command_` +
+
will open the man page in your web browser

* `git gui` +
+
will open up a basic GUI client to staging changes and making commits.

* `gitk --all` +
+
will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.

You might also want to explore using a freely available equivalent such as link:https://www.sourcetreeapp.com/[Atlassian SourceTree].

For further reading, see:

* http://www.kernel.org/pub/software/scm/git/docs/git-config.html[git config man page]
* http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html[.gitattributes man page]
* http://git-scm.com/docs/gitattributes[.gitattributes git-scm.com docs]

== Installing Java

Apache Isis is compatible with Java 7 and Java 8.  For every-day use, the framework is usually compiled against Java 8.

Releases however are xref:comguide:ROOT:cutting-a-release.adoc[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]).

Therefore install either/both of Java 7 JDK and Java 8 JDK.  Note that the JRE is _not_ sufficient.

[TIP]
====
If you intend to contribute back patches to Apache Isis, note that while you can develop using Java 8 within your IDE,
be sure not to use any Java 8 APIs.
====

=== Configure Maven toolchains plugin

If you are a committer that will be performing releases of Apache Isis, then you _must_ configure the
link:http://maven.apache.org/plugins/maven-toolchains-plugin/[toolchains] plugin so that releases can be built using
Java 7.

This is done by placing the `toolchains.xml` file in `~/.m2` directory.  Use the following file as a template,
adjusting paths for your platform:

[source,xml]
----
<?xml version="1.0" encoding="UTF8"?>
<toolchains>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.8</version>
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/usr/lib64/jvm/jdk1.8.0_65</jdkHome>
            <!--
            <jdkHome>c:\Program Files\Java\jdk1.8.0_65</jdkHome>
            -->
        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.7</version>   <!--1-->
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/usr/lib64/jvm/jdk1.7.0_79</jdkHome>
            <!--
            <jdkHome>c:\Program Files\Java\jdk1.7.0_79</jdkHome>
            -->
        </configuration>
    </toolchain>
</toolchains>
----
<1> The Apache Isis build is configured to search for the (`1.7, oracle`) JDK toolchain.

The Apache Isis parent `pom.xml` activates this plugin whenever the `apache-release` profile is enabled.

== Installing Maven

Install Maven 3.0.x, downloadable http://maven.apache.org/download.html[here].

Set `MAVEN_OPTS` environment variable:

[source,bash]
----
export MAVEN_OPTS="-Xms512m -Xmx1024m"
----

== Building all of Apache Isis

To build the source code from the command line, simply go to the root directory and type:

[source,bash]
----
mvn clean install
----

The first time you do this, you'll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.

Thereafter you can speed up the build by adding the `-o` (offline flag).  To save more time still, we also recommend that you build in parallel.  (Per this link:http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/[blog post]), you could also experiment with a number of JDK parameters that we've found also speed up Maven:

[source,bash]
----
export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1"
mvn clean install -o -T1C
----

For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.

When using Eclipse, a Maven profile is configured such that Eclipse compiles to `target-ide` directory rather than the usual `target` directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.

== Checking for Vulnerabilities

Apache Isis configures the link:https://www.owasp.org/index.php/Main_Page[OWASP] link:https://www.owasp.org/index.php/OWASP_Dependency_Check[dependency check] link:http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html[Maven plugin] to determine whether the framework uses libraries that are known to have security vulnerabilities.

To check, run:

[source,bash]
----
mvn org.owasp:dependency-check-maven:aggregate -Dowasp
----

This will generate a single report under `target/dependency-check-report.html`.

[NOTE]
====
The first time this runs can take 10~20 minutes to download the NVD data feeds.
====

To disable, either run in offline mode (add `-o` or `--offline`) or omit the `owasp` property.

== Checking for use of internal JDK APIs

Apache Isis configures the link:https://maven.apache.org/plugins-archives/maven-jdeps-plugin-3.0.0/[jdeps maven plugin] to check for any usage of internal JDK APIs.  This is in preparation for Java 9 module system (Jigsaw) which will prevent such usage of APIs.

To check, run:

[source,bash]
----
mvn clean install -Djdeps
----

This will fail the build on any module that currently uses an internal JDK API.

[WARNING]
====
At the time of writing the `isis-core-schema` module fails the build.
====

[[building-apache-isis]]
= Building Apache Isis
:notice: licensed to the apache software foundation (asf) under one or more contributor license agreements. see the notice file distributed with this work for additional information regarding copyright ownership. the asf licenses this file to you under the apache license, version 2.0 (the "license"); you may not use this file except in compliance with the license. you may obtain a copy of the license at. http://www.apache.org/licenses/license-2.0 . unless required by applicable law or agreed to in writing, software distributed under the license is distributed on an "as is" basis, without warranties or  conditions of any kind, either express or implied. see the license for the specific language governing permissions and limitations under the license.
:page-partial:

== Git

The Apache Isis source code lives in a git repo.

=== Installation

The easiest place to get hold of command-line git is probably the http://git-scm.com/downloads[github download page].

On Windows, this also installs the rather good mSysGit Unix shell. We recommend that you enable git for both the mSysgit and the Windows command prompt:

image::building-apache-isis/setting-up-git.png[width="350px",link="{imagesdir}/building-apache-isis/setting-up-git.png"]

Once git is installed, the two main command line tools to note are:

* `git` command line tool
* `gitk` for viewing the commit history

If using Windows, note that github also have a dedicated https://help.github.com/articles/set-up-git[Windows client]. With a little http://haacked.com/archive/2012/05/30/using-github-for-windows-with-non-github-repositories.aspx[hacking around], it can also be made to work with non-github repositories.

If using Mac, you might also want to check out Atlassian's http://www.atlassian.com/software/sourcetree/overview[Sourcetree].

==== Cloning the Apache Isis repo

First, clone the Apache Isis repo:

[source,bash]
----
git clone https://github.com/apache/isis.git
----

==== Configuring Git

Next up is to configure your user name and password:

[source,bash]
----
git config user.name "My Name Here"
git config user.email myusername@apache.org
----

Next, configure the `core.autocrlf` so that line endings are normalized to LF (Unix style) in the rep; again see https://git-wip-us.apache.org/[Apache's git] page:

* on Windows, use: +
+
[source,bash]
----
git config core.autocrlf true
----

* on Mac/Linux, use: +
+
[source,bash]
----
git config core.autocrlf input
----

The Windows setting means that files are converted back to CRLF on checkout; the Mac/Linux setting means that the file is left as LF on checkout.

We also recommend setting `core.safecrlf`, which aims to ensure that any line ending conversion is repeatable. Do this on all platforms:

[source,bash]
----
git config core.safecrlf true
----

Note that these settings are supplemented in the repo by the `.gitattributes` file and that explicitly specifies line handling treatment for most of the common file types that we have.

Next, we recommend you setup this a refspec so that you can distinguish remote tags from local ones. To do that, locate the `[remote "origin"]` section in your `.git/config` and add the third entry shown below:

[source,bash]
----
[remote "origin"]
    url = ... whatever ...
    fetch = ... whatever ...
    fetch = +refs/tags/*:refs/tags/origin/*
----

This will ensure that a `git fetch` or `git pull` places any remote tags under `origin/xxx.  For example, the`isis-1.0.0`tag on the origin will appear under`origin/isis-1.0.0`.

If you don't use git outside of Apache, you can add the `--global` flag so that the above settings apply for all repos managed by git on your PC.

=== Getting help

Three commands of git that in particular worth knowing:

* `git help _command_` +
+
will open the man page in your web browser

* `git gui` +
+
will open up a basic GUI client to staging changes and making commits.

* `gitk --all` +
+
will open the commit history for all branches. In particular, you should be able to see the local `master`, which branch you are working on (the `HEAD`), and also the last known position of the `master` branch from the central repo, called `origin/master`.

You might also want to explore using a freely available equivalent such as link:https://www.sourcetreeapp.com/[Atlassian SourceTree].

For further reading, see:

* http://www.kernel.org/pub/software/scm/git/docs/git-config.html[git config man page]
* http://www.kernel.org/pub/software/scm/git/docs/gitattributes.html[.gitattributes man page]
* http://git-scm.com/docs/gitattributes[.gitattributes git-scm.com docs]

== Installing Java

Apache Isis is compatible with Java 7 and Java 8.  For every-day use, the framework is usually compiled against Java 8.

Releases however are xref:comguide:ROOT:cutting-a-release.adoc[cut] using Java 7, leveraging the link:http://maven.apache.org/plugins/maven-toolchains-plugin/[Maven toolchains plugin]).

Therefore install either/both of Java 7 JDK and Java 8 JDK.  Note that the JRE is _not_ sufficient.

[TIP]
====
If you intend to contribute back patches to Apache Isis, note that while you can develop using Java 8 within your IDE,
be sure not to use any Java 8 APIs.
====

=== Configure Maven toolchains plugin

If you are a committer that will be performing releases of Apache Isis, then you _must_ configure the
link:http://maven.apache.org/plugins/maven-toolchains-plugin/[toolchains] plugin so that releases can be built using
Java 7.

This is done by placing the `toolchains.xml` file in `~/.m2` directory.  Use the following file as a template,
adjusting paths for your platform:

[source,xml]
----
<?xml version="1.0" encoding="UTF8"?>
<toolchains>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.8</version>
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/usr/lib64/jvm/jdk1.8.0_65</jdkHome>

        </configuration>
    </toolchain>
    <toolchain>
        <type>jdk</type>
        <provides>
            <version>1.7</version>
            <vendor>oracle</vendor>
        </provides>
        <configuration>
            <jdkHome>/usr/lib64/jvm/jdk1.7.0_79</jdkHome>

        </configuration>
    </toolchain>
</toolchains>
----
<1> The Apache Isis build is configured to search for the (`1.7, oracle`) JDK toolchain.

The Apache Isis parent `pom.xml` activates this plugin whenever the `apache-release` profile is enabled.

== Installing Maven

Install Maven 3.0.x, downloadable http://maven.apache.org/download.html[here].

Set `MAVEN_OPTS` environment variable:

[source,bash]
----
export MAVEN_OPTS="-Xms512m -Xmx1024m"
----

== Building all of Apache Isis

To build the source code from the command line, simply go to the root directory and type:

[source,bash]
----
mvn clean install
----

The first time you do this, you'll find it takes a while since Maven needs to download all of the Apache Isis prerequisites.

Thereafter you can speed up the build by adding the `-o` (offline flag).  To save more time still, we also recommend that you build in parallel.  (Per this link:http://zeroturnaround.com/rebellabs/your-maven-build-is-slow-speed-it-up/[blog post]), you could also experiment with a number of JDK parameters that we've found also speed up Maven:

[source,bash]
----
export MAVEN_OPTS="-Xms512m -Xmx1024m -XX:+TieredCompilation -XX:TieredStopAtLevel=1"
mvn clean install -o -T1C
----

For the most part, though, you may want to rely on an IDE such as Eclipse to build the codebase for you. Both Eclipse and Idea (12.0+) support incremental background compilation.

When using Eclipse, a Maven profile is configured such that Eclipse compiles to `target-ide` directory rather than the usual `target` directory. You can therefore switch between Eclipse and Maven command line without one interfering with the other.

== Checking for Vulnerabilities

Apache Isis configures the link:https://www.owasp.org/index.php/Main_Page[OWASP] link:https://www.owasp.org/index.php/OWASP_Dependency_Check[dependency check] link:http://jeremylong.github.io/DependencyCheck/dependency-check-maven/index.html[Maven plugin] to determine whether the framework uses libraries that are known to have security vulnerabilities.

To check, run:

[source,bash]
----
mvn org.owasp:dependency-check-maven:aggregate -Dowasp
----

This will generate a single report under `target/dependency-check-report.html`.

[NOTE]
====
The first time this runs can take 10~20 minutes to download the NVD data feeds.
====

To disable, either run in offline mode (add `-o` or `--offline`) or omit the `owasp` property.

== Checking for use of internal JDK APIs

Apache Isis configures the link:https://maven.apache.org/plugins-archives/maven-jdeps-plugin-3.0.0/[jdeps maven plugin] to check for any usage of internal JDK APIs.  This is in preparation for Java 9 module system (Jigsaw) which will prevent such usage of APIs.

To check, run:

[source,bash]
----
mvn clean install -Djdeps
----

This will fail the build on any module that currently uses an internal JDK API.

[WARNING]
====
At the time of writing the `isis-core-schema` module fails the build.
====


Update 2017-01-04-Keep-English-Learn.adoc

= Keep: English Learn
:icons: font
:published_at: 2017-01-04
:hp-tags: keep, notes, english, learn, links
---

++++
<iframe width="854" height="480" src="https://www.youtube.com/embed/1xsyULVN6UU?ecver=1" frameborder="0" allowfullscreen></iframe>
++++

#*Iniciante*#

1. https://www.udemy.com/cursodeinglesbasico25/[Curso de Inglês Básico Começando de Zero Entenda 25%]
1. https://www.duolingo.com/[Duolingo]
1. https://www.memrise.com/[Memrise]
1. http://aulasdeinglesgratis.net/textos-em-ingles-para-iniciantes-com-audio/[Textos em Inglês para Iniciante]

#*Básico*#

1. https://www.youtube.com/playlist?list=PLo_-eIfuDFyFGfQihJwQT6dTO42E7IZvv[Canal do Beto Ferreira - Nível Básico]
1. https://www.youtube.com/playlist?list=PL7BDB07039775D0A6[Canal Inglês Winner - Nível Básico]
1. https://play.google.com/store/apps/details?id=br.com.ingleswinner[App do Inglês Winner - Acesso a todas as aulas]
1. http://www.mairovergara.com/caigdg[Guia Definitivo - Mairo Vergara]
1. https://www.youtube.com/user/MairoVergara/playlists[Mini-aulas e Dicas de Inglês - Mairo Vergara]
1. http://www.fiction.us/[Livros / Dicionário ou tradutor para analisar pronuncia]

#*Conversação*#

1. https://www.eslpod.com/website/show_all.php?cat_id=-39570#[Podcast - Want to be Fluent in English?]
1. http://aprenderpalavras.com/curso-de-ingles-mairo-vergara/[Curso Mairo Vergara 3.0 - Pago ou Deep Web]
1. http://aulasdeinglesgratis.net/100-conversacoes-em-ingles/[100 Conversações - Texto EN/PT]
1. http://aulasdeinglesgratis.net/100-textos-em-ingles-com-traducao-e-audio/[Textos em InglêsPortuguês e Áudio]
1. https://www.youtube.com/channel/UCGxIAAnrhkCy6H2DRz-t6Qw[Aprenda Inglês se Divertindo - Tim Explica (Gringo)]
1. https://www.edx.org/course/conversational-english-skills-tsinghuax-30640014x-1[Conversational English Skills (EDX)]

#*Complemento*#

*_Inglês com Seriados (Friends, How i met your Mother, Everybody hates Chris e My Wife & Kids)_*

1. *Método*:
- Passo 1 - Dublagem original / Legenda Português
- Passo 2 - Dublagem original / Legenda Inglês
- Passo 3 - Dublagem original / Sem legenda

*_Inglês com Filmes (Matrix, (500) Days of Summer, Toy Store, Para Sempre Alice, Harry Potter e The GodFather)_*

1. *Método*: _O mesmo usado para seriados, mas pode ser aplicado apenas em cenas com bastante dialogo._

	- Passo 1 - Dublagem original / Legenda Português
	- Passo 2 - Dublagem original / Legenda Inglês
	- Passo 3 - Dublagem original / Sem legenda

#*Vlogs/Canais*#

1. https://www.youtube.com/user/schooloflifechannel/playlists[School of Life]
1. https://www.youtube.com/user/crashcourse/playlists[Crash Course]
1. https://www.youtube.com/channel/UC2vUKoTGIwNYq4LO0YWKPIg[Youtuber Gamer - HappyConsoleGamer]
1. https://www.youtube.com/channel/UC3LqW4ijMoENQ2Wv17ZrFJA[Cultura Pop - PBS Idea Channel]
1. https://www.youtube.com/user/scishow/featured[Science Channel - SciShow]

#*Canais no Youtube*#

1. https://www.youtube.com/watch?v=RY1r70I_Doo[Felipe Neto: COMO EU APRENDI INGLÊS (E VOCÊ TAMBÉM VAI APRENDER)]

1. https://www.youtube.com/channel/UCDyjlawtWnY7j1C2RyObZlg[Mairo Vergara]
1. https://www.youtube.com/channel/UCNirOQBP88BVoRZD0GtS9xQ[Canal do Paulo Nideck]
1. https://www.youtube.com/channel/UCskEPRzGlsYHs_a5SJyCXag[Canal SmallAdvantages]
1. https://www.youtube.com/channel/UC15HDk6sVZvWFomxNTMr3zw[Canal Cintia disse]
1. https://www.youtube.com/channel/UCcNm9fM9V5wf-0PZVmkM08g[Carina Fragozo]
1. https://www.youtube.com/channel/UCX1Khol-7w7ZUbDPngo_-0g[Canal Juliana Selem]
1. https://www.youtube.com/channel/UCVBErcpqaokOf4fI5j73K_w[Learn English with Emma [engVid]]

#*Extensões do Chrome*#

1. https://chrome.google.com/webstore/detail/google-dictionary-by-goog/mgijmajocgfcbeboacabfgobmjgjcoja[Google Dictionary (by Google)]
1. https://chrome.google.com/webstore/detail/grammarly-for-chrome/kbfnbcaeplbcioakkpcpgfkobkghlhen[Grammarly for Chrome]

> Fonte https://goo.gl/oeWUdp[Lucas Santana]

= Keep: English Learn
:icons: font
:published_at: 2017-01-04
:hp-tags: keep, notes, english, learn, links
---

#*Iniciante*#

1. https://www.udemy.com/cursodeinglesbasico25/[Curso de Inglês Básico Começando de Zero Entenda 25%]
1. https://www.duolingo.com/[Duolingo]
1. https://www.memrise.com/[Memrise]
1. http://aulasdeinglesgratis.net/textos-em-ingles-para-iniciantes-com-audio/[Textos em Inglês para Iniciante]

#*Básico*#

1. https://www.youtube.com/playlist?list=PLo_-eIfuDFyFGfQihJwQT6dTO42E7IZvv[Canal do Beto Ferreira - Nível Básico]
1. https://www.youtube.com/playlist?list=PL7BDB07039775D0A6[Canal Inglês Winner - Nível Básico]
1. https://play.google.com/store/apps/details?id=br.com.ingleswinner[App do Inglês Winner - Acesso a todas as aulas]
1. http://www.mairovergara.com/caigdg[Guia Definitivo - Mairo Vergara]
1. https://www.youtube.com/user/MairoVergara/playlists[Mini-aulas e Dicas de Inglês - Mairo Vergara]
1. http://www.fiction.us/[Livros / Dicionário ou tradutor para analisar pronuncia]

#*Conversação*#

1. https://www.eslpod.com/website/show_all.php?cat_id=-39570#[Podcast - Want to be Fluent in English?]
1. http://aprenderpalavras.com/curso-de-ingles-mairo-vergara/[Curso Mairo Vergara 3.0 - Pago ou Deep Web]
1. http://aulasdeinglesgratis.net/100-conversacoes-em-ingles/[100 Conversações - Texto EN/PT]
1. http://aulasdeinglesgratis.net/100-textos-em-ingles-com-traducao-e-audio/[Textos em InglêsPortuguês e Áudio]
1. https://www.youtube.com/channel/UCGxIAAnrhkCy6H2DRz-t6Qw[Aprenda Inglês se Divertindo - Tim Explica (Gringo)]
1. https://www.edx.org/course/conversational-english-skills-tsinghuax-30640014x-1[Conversational English Skills (EDX)]

#*Complemento*#

*_Inglês com Seriados (Friends, How i met your Mother, Everybody hates Chris e My Wife & Kids)_*

1. *Método*:
- Passo 1 - Dublagem original / Legenda Português
- Passo 2 - Dublagem original / Legenda Inglês
- Passo 3 - Dublagem original / Sem legenda

*_Inglês com Filmes (Matrix, (500) Days of Summer, Toy Store, Para Sempre Alice, Harry Potter e The GodFather)_*

1. *Método*: _O mesmo usado para seriados, mas pode ser aplicado apenas em cenas com bastante dialogo._

	- Passo 1 - Dublagem original / Legenda Português
	- Passo 2 - Dublagem original / Legenda Inglês
	- Passo 3 - Dublagem original / Sem legenda

#*Vlogs/Canais*#

1. https://www.youtube.com/user/schooloflifechannel/playlists[School of Life]
1. https://www.youtube.com/user/crashcourse/playlists[Crash Course]
1. https://www.youtube.com/channel/UC2vUKoTGIwNYq4LO0YWKPIg[Youtuber Gamer - HappyConsoleGamer]
1. https://www.youtube.com/channel/UC3LqW4ijMoENQ2Wv17ZrFJA[Cultura Pop - PBS Idea Channel]
1. https://www.youtube.com/user/scishow/featured[Science Channel - SciShow]

#*Canais no Youtube*#

1. https://www.youtube.com/watch?v=RY1r70I_Doo[Felipe Neto: COMO EU APRENDI INGLÊS (E VOCÊ TAMBÉM VAI APRENDER)]

1. https://www.youtube.com/channel/UCDyjlawtWnY7j1C2RyObZlg[Mairo Vergara]
1. https://www.youtube.com/channel/UCNirOQBP88BVoRZD0GtS9xQ[Canal do Paulo Nideck]
1. https://www.youtube.com/channel/UCskEPRzGlsYHs_a5SJyCXag[Canal SmallAdvantages]
1. https://www.youtube.com/channel/UC15HDk6sVZvWFomxNTMr3zw[Canal Cintia disse]
1. https://www.youtube.com/channel/UCcNm9fM9V5wf-0PZVmkM08g[Carina Fragozo]
1. https://www.youtube.com/channel/UCX1Khol-7w7ZUbDPngo_-0g[Canal Juliana Selem]
1. https://www.youtube.com/channel/UCVBErcpqaokOf4fI5j73K_w[Learn English with Emma [engVid]]

#*Extensões do Chrome*#

1. https://chrome.google.com/webstore/detail/google-dictionary-by-goog/mgijmajocgfcbeboacabfgobmjgjcoja[Google Dictionary (by Google)]
1. https://chrome.google.com/webstore/detail/grammarly-for-chrome/kbfnbcaeplbcioakkpcpgfkobkghlhen[Grammarly for Chrome]

> Fonte https://goo.gl/oeWUdp[Lucas Santana]