Documentation
Project: http://git-wip-us.apache.org/repos/asf/zest-qi4j/repo Commit: http://git-wip-us.apache.org/repos/asf/zest-qi4j/commit/9a170ed6 Tree: http://git-wip-us.apache.org/repos/asf/zest-qi4j/tree/9a170ed6 Diff: http://git-wip-us.apache.org/repos/asf/zest-qi4j/diff/9a170ed6 Branch: refs/heads/master Commit: 9a170ed682914e14ccacdc79476e8e28c6c88512 Parents: 827c41b Author: Paul Merlin <[email protected]> Authored: Sat Apr 13 18:24:02 2013 +0200 Committer: Paul Merlin <[email protected]> Committed: Sat Apr 13 18:24:02 2013 +0200 ---------------------------------------------------------------------- buildSrc/build.gradle | 2 ++ core/api/src/docs/concern.txt | 6 ++-- .../api/activation/ActivationEventsTest.java | 6 ++-- core/spi/src/docs/cache.txt | 4 +++ core/spi/src/docs/entitystore.txt | 4 +++ core/spi/src/docs/indexing.txt | 4 +++ core/spi/src/docs/spi.txt | 14 ++++----- core/spi/src/docs/valueserialization.txt | 14 ++++++++- ...AbstractValueCompositeSerializationTest.java | 26 +++++++++++++++- .../bootstrap/Qi4jApplicationBootstrap.java | 4 ++- .../bootstrap/internal/application/package.html | 5 +++ .../spring/bootstrap/internal/package.html | 5 +++ .../bootstrap/internal/service/package.html | 5 +++ .../qi4j/library/spring/bootstrap/package.html | 5 +++ .../qi4j/library/spring/importer/package.html | 5 +++ manual/build.gradle | 5 +-- .../tutorials/howto-assembly-application.txt | 6 ++++ .../docs/tutorials/howto-configure-service.txt | 6 ++++ .../tutorials/howto-contextual-fragments.txt | 8 ++++- .../src/docs/tutorials/howto-create-concern.txt | 6 ++++ .../docs/tutorials/howto-create-constraint.txt | 6 ++++ .../src/docs/tutorials/howto-create-entity.txt | 9 ++++++ .../docs/tutorials/howto-create-sideeffect.txt | 6 ++++ .../tutorials/howto-leverage-properties.txt | 8 ++++- manual/src/docs/tutorials/howto-use-io.txt | 11 +++++-- .../src/docs/tutorials/howto-writing-docs.txt | 4 ++- tutorials/composites/src/docs/step5.txt | 32 ++++++++++---------- .../composites/src/docs/tut-composites.txt | 7 +++++ .../tenminutes/src/docs/ten-minutes.txt | 10 ++++++ .../thirtyminutes/src/docs/thirty-minutes.txt | 10 ++++++ .../twominutes/src/docs/two-minutes.txt | 7 +++++ tutorials/services/src/docs/tut-services.txt | 7 +++++ 32 files changed, 218 insertions(+), 39 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/buildSrc/build.gradle ---------------------------------------------------------------------- diff --git a/buildSrc/build.gradle b/buildSrc/build.gradle new file mode 100644 index 0000000..139597f --- /dev/null +++ b/buildSrc/build.gradle @@ -0,0 +1,2 @@ + + http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/api/src/docs/concern.txt ---------------------------------------------------------------------- diff --git a/core/api/src/docs/concern.txt b/core/api/src/docs/concern.txt index 422077d..6a941fb 100644 --- a/core/api/src/docs/concern.txt +++ b/core/api/src/docs/concern.txt @@ -84,13 +84,13 @@ NOTE: Even if a method fulfills the requirement for the concern, if the concern == Invocation Order == -The concerns are invoked AFTER all <<core-api-constraints>> have been checked. The concerns are executed before the -<<core-api.sideeffects>> are executed in the return path. +The concerns are invoked AFTER all <<core-api-constraint>> have been checked. The concerns are executed before the +<<core-api-sideeffect>> are executed in the return path. The order of execution is defined by the declaration order, interface hierarchy, whether the concern is generic or typed and if they are declared in the interface or declared in the <<core-bootstrap-assembly>>. -From the perspective of incoming call, i.e. after the <core-api-constraints>> have been checked, the following rules +From the perspective of incoming call, i.e. after the <core-api-constraint>> have been checked, the following rules are in place; * Typed concerns are invoked AFTER Generic concerns. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/api/src/test/java/org/qi4j/api/activation/ActivationEventsTest.java ---------------------------------------------------------------------- diff --git a/core/api/src/test/java/org/qi4j/api/activation/ActivationEventsTest.java b/core/api/src/test/java/org/qi4j/api/activation/ActivationEventsTest.java index 9caa92c..18fcc38 100644 --- a/core/api/src/test/java/org/qi4j/api/activation/ActivationEventsTest.java +++ b/core/api/src/test/java/org/qi4j/api/activation/ActivationEventsTest.java @@ -15,8 +15,6 @@ */ package org.qi4j.api.activation; -import org.qi4j.api.activation.ActivationEvent; -import org.qi4j.api.activation.ActivationEventListener; import java.util.ArrayList; import java.util.Iterator; import java.util.List; @@ -30,7 +28,7 @@ import org.qi4j.bootstrap.AssemblyException; import org.qi4j.bootstrap.ModuleAssembly; import org.qi4j.bootstrap.SingletonAssembler; -import static junit.framework.Assert.*; +import static org.junit.Assert.*; import static org.qi4j.api.activation.ActivationEvent.EventType.*; public class ActivationEventsTest @@ -45,6 +43,7 @@ public class ActivationEventsTest implements TestService { + @Override public void test() { } @@ -253,6 +252,7 @@ public class ActivationEventsTest this.events = events; } + @Override public void onEvent( ActivationEvent event ) { events.add( event ); http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/spi/src/docs/cache.txt ---------------------------------------------------------------------- diff --git a/core/spi/src/docs/cache.txt b/core/spi/src/docs/cache.txt index e69de29..273dc01 100644 --- a/core/spi/src/docs/cache.txt +++ b/core/spi/src/docs/cache.txt @@ -0,0 +1,4 @@ +[[core-spi-cache,Cache SPI]] += Cache SPI = + +NOTE: This SPI has no documentation yet. Learn how to contribute in <<community-docs>>. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/spi/src/docs/entitystore.txt ---------------------------------------------------------------------- diff --git a/core/spi/src/docs/entitystore.txt b/core/spi/src/docs/entitystore.txt index e69de29..6bfa50e 100644 --- a/core/spi/src/docs/entitystore.txt +++ b/core/spi/src/docs/entitystore.txt @@ -0,0 +1,4 @@ +[[core-spi-entitystore,EntityStore SPI]] += EntityStore SPI = + +NOTE: This SPI has no documentation yet. Learn how to contribute in <<community-docs>>. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/spi/src/docs/indexing.txt ---------------------------------------------------------------------- diff --git a/core/spi/src/docs/indexing.txt b/core/spi/src/docs/indexing.txt index e69de29..5ff1361 100644 --- a/core/spi/src/docs/indexing.txt +++ b/core/spi/src/docs/indexing.txt @@ -0,0 +1,4 @@ +[[core-spi-indexing,Indexing/Query SPI]] += Indexing/Query SPI = + +NOTE: This SPI has no documentation yet. Learn how to contribute in <<community-docs>>. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/spi/src/docs/spi.txt ---------------------------------------------------------------------- diff --git a/core/spi/src/docs/spi.txt b/core/spi/src/docs/spi.txt index c910950..305449f 100644 --- a/core/spi/src/docs/spi.txt +++ b/core/spi/src/docs/spi.txt @@ -29,11 +29,11 @@ include::../../build/docs/buildinfo/artifact.txt[] There are currently 5 Core SPI extensions; - * ValueSerialization SPI - * EntityStore SPI - * Cache SPI - * Indexing/Query SPI - * Metrics SPI + * <<core-spi-valueserialization>> + * <<core-spi-entitystore>> + * <<core-spi-cache>> + * <<core-spi-indexing>> + * <<core-spi-metrics>> Qi4j Runtime Extensions implementations may depend on Qi4j Libraries, but Libraries are NOT ALLOWED to depend on Extensions. Applications code is NOT ALLOWED to depend on extensions. And application code SHOULD NOT depend on the @@ -50,11 +50,11 @@ include::entitystore.txt[] :leveloffset: {level3} -// include::cache.txt[] +include::cache.txt[] :leveloffset: {level3} -// include::indexing.txt[] +include::indexing.txt[] :leveloffset: {level3} http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/spi/src/docs/valueserialization.txt ---------------------------------------------------------------------- diff --git a/core/spi/src/docs/valueserialization.txt b/core/spi/src/docs/valueserialization.txt index 9029cbc..2696cf3 100644 --- a/core/spi/src/docs/valueserialization.txt +++ b/core/spi/src/docs/valueserialization.txt @@ -1,6 +1,18 @@ [[core-spi-valueserialization,ValueSerialization SPI]] = ValueSerialization SPI = +== Overview == + +The Qi4j Core Runtime use ValueSerialization to provide string representation of ValueComposites via their `toString()` +method, and, their instanciation from the very same representation via the `newValueFromSerializedState(..)` method of +the ValueBuilderFactory API. + +If no ValueSerialization service is visible, a default implementation supporting the JSON format used but note that it +won't be available as a Service. So, in order to use the full ValueSerialization API a ValueSerialization service must +be explicitely assembled in the Application. See the <<extensions>> documentation for details. + +== Implementation notes == + Simply implement ValueSerialization to create an extension for the ValueSerialization SPI. The Core SPI module provides adapters to create pull-parsing capable ValueSerializers and pull-parsing and tree-parsing capable ValueDeserializers. @@ -10,7 +22,7 @@ nothing stops you from implementing an extension for the ValueSerialization SPI Theses adapters are tailored for serialization mechanisms that support the following two structures that can be nested: - * an collection of name/value pairs. In various languages, this is realized as an object, record, struct, + * a collection of name/value pairs. In various languages, this is realized as an object, record, struct, dictionary, hash table, keyed list, or associative array, * an ordered list of values. In most languages, this is realized as an array, vector, list, or sequence ; http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/core/testsupport/src/main/java/org/qi4j/test/value/AbstractValueCompositeSerializationTest.java ---------------------------------------------------------------------- diff --git a/core/testsupport/src/main/java/org/qi4j/test/value/AbstractValueCompositeSerializationTest.java b/core/testsupport/src/main/java/org/qi4j/test/value/AbstractValueCompositeSerializationTest.java index 4fadd75..f724ffb 100644 --- a/core/testsupport/src/main/java/org/qi4j/test/value/AbstractValueCompositeSerializationTest.java +++ b/core/testsupport/src/main/java/org/qi4j/test/value/AbstractValueCompositeSerializationTest.java @@ -58,7 +58,9 @@ import static org.junit.Assert.*; /** * Assert that ValueSerialization behaviour on ValueComposites is correct. */ -// TODO Assert Association and ManyAssociation serialization behavior ! +// TODO Assert Association and ManyAssociation serialization behaviour! +// TODO Assert Arrays behaviour! +// TODO Assert Generics behaviour! public abstract class AbstractValueCompositeSerializationTest extends AbstractQi4jTest { @@ -185,6 +187,17 @@ public abstract class AbstractValueCompositeSerializationTest proto.customFoo().set( module.newValue( CustomFooValue.class ) ); proto.customFooValue().set( module.newValue( CustomFooValue.class ) ); + // Arrays + // TODO FIXME Disabled as ValueComposite equality fails here + //proto.primitiveByteArray().set( new byte[] + // { + // 9, -12, 42, -12, 127, 23, -128, 73 + // } ); + //proto.byteArray().set( new Byte[] + // { + // 9, null, -12, 23, -12, 127, -128, 73 + // } ); + // NestedEntities proto.barAssociation().set( buildBarEntity( "bazar in barAssociation" ) ); proto.barEntityAssociation().set( buildBarEntity( "bazar in barEntityAssociation" ) ); @@ -262,6 +275,17 @@ public abstract class AbstractValueCompositeSerializationTest @UseDefaults Property<TestEnum> testEnum(); + // TODO FIXME Disabled as ValueComposite equality fails here + //Property<byte[]> primitiveByteArray(); + // + //@Optional + //Property<byte[]> primitiveByteArrayNull(); + // + //Property<Byte[]> byteArray(); + // + //@Optional + //Property<Byte[]> byteArrayNull(); + Property<Object> serializable(); Property<Foo> foo(); http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/Qi4jApplicationBootstrap.java ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/Qi4jApplicationBootstrap.java b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/Qi4jApplicationBootstrap.java index 8fb2080..1145ef5 100644 --- a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/Qi4jApplicationBootstrap.java +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/Qi4jApplicationBootstrap.java @@ -22,7 +22,9 @@ import org.qi4j.bootstrap.ModuleAssembly; import org.springframework.context.ApplicationContextAware; /** - * Steps to export qi4j service: + * Run a Qi4j Application as a Spring Bean and export its Services to Spring. + * + * Steps to export Qi4j service: * <ul> * <li>Create spring BeanFactory service of qi4j services to export.</li> * <li>Create a class that extends {@link Qi4jApplicationBootstrap}.</li> http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/application/package.html ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/application/package.html b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/application/package.html new file mode 100644 index 0000000..4bd5c19 --- /dev/null +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/application/package.html @@ -0,0 +1,5 @@ +<html> + <body> + <h2>Spring Integration internal package.</h2> + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/package.html ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/package.html b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/package.html new file mode 100644 index 0000000..4bd5c19 --- /dev/null +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/package.html @@ -0,0 +1,5 @@ +<html> + <body> + <h2>Spring Integration internal package.</h2> + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/service/package.html ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/service/package.html b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/service/package.html new file mode 100644 index 0000000..4bd5c19 --- /dev/null +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/internal/service/package.html @@ -0,0 +1,5 @@ +<html> + <body> + <h2>Spring Integration internal package.</h2> + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/package.html ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/package.html b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/package.html new file mode 100644 index 0000000..4427a23 --- /dev/null +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/bootstrap/package.html @@ -0,0 +1,5 @@ +<html> + <body> + <h2>Run a Qi4j Application as a Spring Bean and export its Services to Spring.</h2> + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/libraries/spring/src/main/java/org/qi4j/library/spring/importer/package.html ---------------------------------------------------------------------- diff --git a/libraries/spring/src/main/java/org/qi4j/library/spring/importer/package.html b/libraries/spring/src/main/java/org/qi4j/library/spring/importer/package.html new file mode 100644 index 0000000..9a4ef36 --- /dev/null +++ b/libraries/spring/src/main/java/org/qi4j/library/spring/importer/package.html @@ -0,0 +1,5 @@ +<html> + <body> + <h2>Import Spring Services inside a Qi4j Application.</h2> + </body> +</html> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/build.gradle ---------------------------------------------------------------------- diff --git a/manual/build.gradle b/manual/build.gradle index 0face61..6528572 100644 --- a/manual/build.gradle +++ b/manual/build.gradle @@ -1,10 +1,11 @@ description = "Qi4j Manuals and Website." dependencies { - compile( project( ":org.qi4j.core:org.qi4j.core.api" ) ) + compile( project( ":org.qi4j.core:org.qi4j.core.bootstrap" ) ) compile( project( ":org.qi4j.libraries:org.qi4j.library.constraints" ) ) compile( project( ":org.qi4j.libraries:org.qi4j.library.logging" ) ) - compile( libraries.slf4j_api ) + runtime( project( ":org.qi4j.core:org.qi4j.core.runtime" ) ) + runtime( libraries.logback ) } http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-assembly-application.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-assembly-application.txt b/manual/src/docs/tutorials/howto-assembly-application.txt index e7f206c..dcb520c 100644 --- a/manual/src/docs/tutorials/howto-assembly-application.txt +++ b/manual/src/docs/tutorials/howto-assembly-application.txt @@ -19,6 +19,12 @@ We receive a lot of questions about how applications should be assembled, and si and everything is to be done programmatically, it escalates the need to provide more hands-on explanation of how this is done. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == Basics == First let's recap the structural requirements of Qi4j; http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-configure-service.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-configure-service.txt b/manual/src/docs/tutorials/howto-configure-service.txt index 8f5e6df..3022b33 100644 --- a/manual/src/docs/tutorials/howto-configure-service.txt +++ b/manual/src/docs/tutorials/howto-configure-service.txt @@ -21,6 +21,12 @@ since you can easily build GUI tools to allow editing of these in runtime. Howev the Configuration instance, Qi4j also does the initial bootstrapping of the Configuration entity for you. This HowTo is going to show how. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == We need a Service == To illustrate these features we create an TravelPlan service, which allows clients to find and make Reservations to http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-contextual-fragments.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-contextual-fragments.txt b/manual/src/docs/tutorials/howto-contextual-fragments.txt index b62cb77..40573c9 100644 --- a/manual/src/docs/tutorials/howto-contextual-fragments.txt +++ b/manual/src/docs/tutorials/howto-contextual-fragments.txt @@ -23,7 +23,13 @@ Typical use-case is tracing and debugging. Other potential uses are additional s access to internal mixins not originally intended for, such as GUI frameworks doing reflection on certain composites. We strongly recommend against using this feature, as it is not needed as commonly as you may think. -Note: Constraints are not supported to be contextual at the moment. +NOTE: Constraints are not supported to be contextual at the moment. + +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. The mixins, sideeffects and concerns are added during the bootstrap phase. It is very straight-forward; http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-create-concern.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-create-concern.txt b/manual/src/docs/tutorials/howto-create-concern.txt index e387d0f..a22aa07 100644 --- a/manual/src/docs/tutorials/howto-create-concern.txt +++ b/manual/src/docs/tutorials/howto-create-concern.txt @@ -3,6 +3,12 @@ Concerns are defined in <<def-concern>>. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == Typed Concern == A typed Concern is a Java class that implements the MixinType it can be used on: http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-create-constraint.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-create-constraint.txt b/manual/src/docs/tutorials/howto-create-constraint.txt index e5a4dde..603f3dd 100644 --- a/manual/src/docs/tutorials/howto-create-constraint.txt +++ b/manual/src/docs/tutorials/howto-create-constraint.txt @@ -3,6 +3,12 @@ Constraints are defined in <<def-constraint>>. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == Method Constraint == Method Constraints are declared with annotations on the method argument. The annotation itself is custom, and it is possible to make your own. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-create-entity.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-create-entity.txt b/manual/src/docs/tutorials/howto-create-entity.txt index 973b928..11d8035 100644 --- a/manual/src/docs/tutorials/howto-create-entity.txt +++ b/manual/src/docs/tutorials/howto-create-entity.txt @@ -19,6 +19,15 @@ One of the most common tasks in Qi4j is the management of the life cycle of Enti delivering much higher performance than traditional Object-Relational Mapping technologies, we also expect that people use Entities more frequently in Qi4j applications, so it is a very important topic to cover. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +Moreover, you'll need an EntityStore for persistence and an Indexing engine for querying. Choose among the available +implementations listed in the <<extensions>> section. + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == Basics First == All Entity operations MUST be done within a UnitOfWork. UnitOfWorks can be nested and if underlying UnitOfWorks are not http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-create-sideeffect.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-create-sideeffect.txt b/manual/src/docs/tutorials/howto-create-sideeffect.txt index 445a260..6c40829 100644 --- a/manual/src/docs/tutorials/howto-create-sideeffect.txt +++ b/manual/src/docs/tutorials/howto-create-sideeffect.txt @@ -3,6 +3,12 @@ SideEffects are defined in <<def-sideeffect>>. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Bootstrap artifact: + +include::../../../../core/bootstrap/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + == Typed SideEffect == A typed SideEffect is a Java class that implements the MixinType it can be used on: http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-leverage-properties.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-leverage-properties.txt b/manual/src/docs/tutorials/howto-leverage-properties.txt index 4dc2828..24bde2c 100644 --- a/manual/src/docs/tutorials/howto-leverage-properties.txt +++ b/manual/src/docs/tutorials/howto-leverage-properties.txt @@ -20,6 +20,12 @@ Qi4j does not follow the JavaBeans standard for property support. Instead, a muc advantages are enormous, and the only real downside is that people are already destroyed, thinking in so called POJO terms. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core API artifact: + +include::../../../../core/api/build/docs/buildinfo/artifact.txt[] + +At runtime you will need the Core Runtime artifact too. See the <<howto-depend-on-qi4j>> tutorial for details. + So in Qi4j, instead of writing; [snippet,java] @@ -65,7 +71,7 @@ tag=create == Persistence == The Property concept also allows a much better defined persistence model. In Qi4j, only Property and Association -instances are persisted, and that makes the semantics around the persistence system very clear. +instances are persisted, and that makes the semantics around the persistence system very clear. Properties reference values only, and these values must be Serializable, which means that Properties can not contain Entities, since Entities are not Serializable. Associations are the opposite, as they must only reference Entities and http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-use-io.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-use-io.txt b/manual/src/docs/tutorials/howto-use-io.txt index d9ec18c..ac1ae10 100644 --- a/manual/src/docs/tutorials/howto-use-io.txt +++ b/manual/src/docs/tutorials/howto-use-io.txt @@ -75,8 +75,15 @@ could do so by changing the 2 and 4 parts to read/write multiple lines at a time == The API == -Once this was identified it was mostly just a matter of putting interfaces on these pieces, and making sure they can be -easily used in many different situations. The result is as follows. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +See the <<howto-depend-on-qi4j>> tutorial for details. + +Once theses parts were identified it was mostly just a matter of putting interfaces on these pieces, and making sure +they can be easily used in many different situations. The result is as follows. To start with we have Input: http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/manual/src/docs/tutorials/howto-writing-docs.txt ---------------------------------------------------------------------- diff --git a/manual/src/docs/tutorials/howto-writing-docs.txt b/manual/src/docs/tutorials/howto-writing-docs.txt index 803f4dc..726aa45 100644 --- a/manual/src/docs/tutorials/howto-writing-docs.txt +++ b/manual/src/docs/tutorials/howto-writing-docs.txt @@ -11,6 +11,8 @@ The cheatsheet is really useful! [[community-docs-overall-flow,Documentation Flow]] == Overall Flow == +TIP: To generate the website locally use `./gradlew -p manual website`. Output is in `~/manual/build/docs/website`. + Each (sub)project has its own documentation, in 'src/docs/' and all the Asciidoc documents have the +.txt+ file extension. The documents can use code snippets which will extract code from the project. This is preferred way to include @@ -38,7 +40,7 @@ This is how a document should start: = The Document Title = ---- -To push the headings down to the right level in the output, the +leveloffset+ +To push the headings down to the right level in the output, the +leveloffset+ attribute is used when including the document inside of another document. Subsequent headings in a document should use the following syntax: http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/composites/src/docs/step5.txt ---------------------------------------------------------------------- diff --git a/tutorials/composites/src/docs/step5.txt b/tutorials/composites/src/docs/step5.txt index a6dac0f..eb49b94 100644 --- a/tutorials/composites/src/docs/step5.txt +++ b/tutorials/composites/src/docs/step5.txt @@ -3,36 +3,36 @@ Previous step was <<tut-composites-step4>>. -In this step we will look at how to use Constraints. When we pass parameters to methods in regular Java code the only -restriction we can make is to denote a type. Any other constraints on the input value, such as whether the parameter is -optional, integer ranges, string regular expressions, and so on, cannot be expressed, and so we have to put this into +In this step we will look at how to use Constraints. When we pass parameters to methods in regular Java code the only +restriction we can make is to denote a type. Any other constraints on the input value, such as whether the parameter is +optional, integer ranges, string regular expressions, and so on, cannot be expressed, and so we have to put this into Javadoc, and then manually add these checks in the implementation class. -In Qi4j there is the option to use Constraints, which are further restrictions on the parameters. This is implemented -by having an annotation that describes what the Constraint does, and then an implementation class that checks whether a +In Qi4j there is the option to use Constraints, which are further restrictions on the parameters. This is implemented +by having an annotation that describes what the Constraint does, and then an implementation class that checks whether a specific value fulfills the Constraint or not. -There are a number of pre-written constraints in Qi4j which you can use. The null check of the original HelloWorld -version is already handled by default since Qi4j considers method parameters to be mandatory if not explicitly marked -with the @Optional annotation. So, instead of doing that check we will add other checks that are useful to make, such +NOTE: The previous steps had a dependency to the <<core-api>> only. The constraints you've used in this step, +introduce a new dependency to the <<library-constraints>>, where all the constraint related classes reside. So +update your classpath settings accordingly. + +There are a number of pre-written constraints in Qi4j which you can use. The null check of the original HelloWorld +version is already handled by default since Qi4j considers method parameters to be mandatory if not explicitly marked +with the @Optional annotation. So, instead of doing that check we will add other checks that are useful to make, such as ensuring that the passed in string is not empty. -The only thing you have to do is add the annotation @NotEmpty to the method parameters you want to constrain in this -way. The annotation has a default implementation declared in it by using the @Constraints annotation. You can either -just use this, which is the common case, or override it by declaring your own @Constraints annotation in the +The only thing you have to do is add the annotation @NotEmpty to the method parameters you want to constrain in this +way. The annotation has a default implementation declared in it by using the @Constraints annotation. You can either +just use this, which is the common case, or override it by declaring your own @Constraints annotation in the TransientComposite type. -You can add as many Constraint annotations you want to a parameter. All of them will be checked whenever a method is +You can add as many Constraint annotations you want to a parameter. All of them will be checked whenever a method is called. Steps for this tutorial: - Add @NotEmpty to the state parameters. -Note: The previous steps had a dependency to the <<core-api>> only. The constraints you've used in this step, -introduce a new dependency to the <<library-constraints>>, where all the constraint related classes reside. So -update your classpath settings accordingly. - == Solution == If you have successfully completed the task, you should end up with the following artifacts; http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/composites/src/docs/tut-composites.txt ---------------------------------------------------------------------- diff --git a/tutorials/composites/src/docs/tut-composites.txt b/tutorials/composites/src/docs/tut-composites.txt index 8b2ef39..2f4060c 100644 --- a/tutorials/composites/src/docs/tut-composites.txt +++ b/tutorials/composites/src/docs/tut-composites.txt @@ -28,6 +28,13 @@ always look at the next tutorial step for guidance on what to do. At the bottom of each tutorial step, the is Solutions section, which list the files you should have come to if you have followed the instructions. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +See the <<howto-depend-on-qi4j>> tutorial for details. + :leveloffset: 3 include::step1.txt[] http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/introduction/tenminutes/src/docs/ten-minutes.txt ---------------------------------------------------------------------- diff --git a/tutorials/introduction/tenminutes/src/docs/ten-minutes.txt b/tutorials/introduction/tenminutes/src/docs/ten-minutes.txt index 66a7c6f..28ad0e3 100644 --- a/tutorials/introduction/tenminutes/src/docs/ten-minutes.txt +++ b/tutorials/introduction/tenminutes/src/docs/ten-minutes.txt @@ -14,6 +14,16 @@ this tutorial, run it and play with it. * Fragments are Mixins, Concerns, Constraints and SideEffects. * Only Mixins carry Composite state. The others are shared between Composite instances. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +Moreover, you'll need an EntityStore for persistence and an Indexing engine for querying. Choose among the available +implementations listed in the <<extensions>> section. + +See the <<howto-depend-on-qi4j>> tutorial for details. + Composition is done with Java interfaces and Annotations. Example; [snippet,java] ----------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/introduction/thirtyminutes/src/docs/thirty-minutes.txt ---------------------------------------------------------------------- diff --git a/tutorials/introduction/thirtyminutes/src/docs/thirty-minutes.txt b/tutorials/introduction/thirtyminutes/src/docs/thirty-minutes.txt index 1e81e54..65ea58a 100644 --- a/tutorials/introduction/thirtyminutes/src/docs/thirty-minutes.txt +++ b/tutorials/introduction/thirtyminutes/src/docs/thirty-minutes.txt @@ -9,6 +9,16 @@ this tutorial, run it and play with it. This introduction will deepen your understanding of Qi4j, as we touches on a couple of the common features of Qi4j. It is expected that you have gone through and understood the "Qi4j in 10 minutes" introduction. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +Moreover, you'll need an EntityStore for persistence and an Indexing engine for querying. Choose among the available +implementations listed in the <<extensions>> section. + +See the <<howto-depend-on-qi4j>> tutorial for details. + We will go back to the OrderEntity example; [snippet,java] ----------- http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/introduction/twominutes/src/docs/two-minutes.txt ---------------------------------------------------------------------- diff --git a/tutorials/introduction/twominutes/src/docs/two-minutes.txt b/tutorials/introduction/twominutes/src/docs/two-minutes.txt index bfbd81e..362429f 100644 --- a/tutorials/introduction/twominutes/src/docs/two-minutes.txt +++ b/tutorials/introduction/twominutes/src/docs/two-minutes.txt @@ -8,6 +8,13 @@ this tutorial, run it and play with it. To show that Qi4j is not necessarily complex, not hard to get going with and easy to deploy, we are first showing the classic HelloWorld, as small as it can get and still be Composite Oriented Programming and not only standard OOP. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +See the <<howto-depend-on-qi4j>> tutorial for details. + Ready, Set, Go! Let's say we want to do the common HelloWorld example, but with a more domain-oriented setting. http://git-wip-us.apache.org/repos/asf/zest-qi4j/blob/9a170ed6/tutorials/services/src/docs/tut-services.txt ---------------------------------------------------------------------- diff --git a/tutorials/services/src/docs/tut-services.txt b/tutorials/services/src/docs/tut-services.txt index e8b7b73..1a65b1f 100644 --- a/tutorials/services/src/docs/tut-services.txt +++ b/tutorials/services/src/docs/tut-services.txt @@ -21,6 +21,13 @@ always look at the next tutorial step for guidance on what to do. At the bottom of each tutorial step, the is Solutions section, which list the files you should have come to if you have followed the instructions. +If you want to reproduce what's explained in this tutorial, remember to depend on the Core Runtime artifact that depends +on Core API, Core SPI, Core Bootstrap and Core Functional & I/O APIs: + +include::../../../../core/runtime/build/docs/buildinfo/artifact.txt[] + +See the <<howto-depend-on-qi4j>> tutorial for details. + :leveloffset: 3 include::step1.txt[]
