Repository: cayenne Updated Branches: refs/heads/master a08ab3710 -> c4e752274
Docs: replace constructor with ServerRuntime.builder() Project: http://git-wip-us.apache.org/repos/asf/cayenne/repo Commit: http://git-wip-us.apache.org/repos/asf/cayenne/commit/c4e75227 Tree: http://git-wip-us.apache.org/repos/asf/cayenne/tree/c4e75227 Diff: http://git-wip-us.apache.org/repos/asf/cayenne/diff/c4e75227 Branch: refs/heads/master Commit: c4e7522745087cf144a2952676f62da75e354d57 Parents: a08ab37 Author: Nikita Timofeev <stari...@gmail.com> Authored: Wed Feb 22 17:24:30 2017 +0300 Committer: Nikita Timofeev <stari...@gmail.com> Committed: Wed Feb 22 17:24:30 2017 +0300 ---------------------------------------------------------------------- .../src/docbkx/customizing-cayenne-runtime.xml | 32 ++++++++++------- .../src/docbkx/starting-cayenne.xml | 37 ++++++++++---------- .../src/docbkx/object-context.xml | 5 +-- 3 files changed, 40 insertions(+), 34 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cayenne/blob/c4e75227/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml index 21719ce..0182e2c 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/customizing-cayenne-runtime.xml @@ -189,8 +189,10 @@ binder.bind(Key.get(Service2.class, "i2")).to(Service2Impl.class);</programlisti // customizations go here... } }</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule(); -ServerRuntime runtime = - new ServerRuntime("com/example/cayenne-mydomain.xml", extensions);</programlisting> +ServerRuntime runtime = ServerRuntime.builder() + .addConfig("com/example/cayenne-mydomain.xml") + .addModule(extensions) + .build();</programlisting> <section xml:id="changing-properties-of-existing-services"> <title>Changing Properties of Existing Services</title> <para>Many built-in Cayenne services change their behavior based on a value of some @@ -338,21 +340,25 @@ public class DoubleArrayType implements ExtendedType { <para>For Java7</para> <programlisting language="java"> // add DoubleArrayType to list of user types -ServerRuntime runtime = new ServerRuntime("cayenne-project.xml", new Module() { - @Override - public void configure(Binder binder) { - binder - .bindList(Constants.SERVER_USER_TYPES_LIST) - .add(new DoubleArrayType()); - } -}); +ServerRuntime runtime = ServerRuntime.builder() + .addConfig("cayenne-project.xml") + .addModule(new Module() { + @Override + public void configure(Binder binder) { + binder + .bindList(Constants.SERVER_USER_TYPES_LIST) + .add(new DoubleArrayType()); + } + }) + .build(); </programlisting> <para>For Java8</para> <programlisting language="java"> // add DoubleArrayType to list of user types -ServerRuntime runtime = new ServerRuntime("cayenne-project.xml", - (Binder binder) -> binder.bindList(Constants.SERVER_USER_TYPES_LIST) - .add(new DoubleArrayType())); +ServerRuntime runtime = ServerRuntime.builder() + .addConfig("cayenne-project.xml") + .addModule(binder -> binder.bindList(Constants.SERVER_USER_TYPES_LIST).add(new DoubleArrayType())) + .build(); </programlisting> <para>More examples of implementation you can find in <link xlink:href="https://github.com/apache/cayenne/tree/master/cayenne-java8";>cayenne-java8 module</link> or http://git-wip-us.apache.org/repos/asf/cayenne/blob/c4e75227/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml b/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml index a1302f9..c8dfdb7 100644 --- a/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml +++ b/docs/docbook/cayenne-guide/src/docbkx/starting-cayenne.xml @@ -21,9 +21,11 @@ <title>Starting and Stopping ServerRuntime</title> <para>In runtime Cayenne is accessed via <code>org.apache.cayenne.configuration.server.ServerRuntime</code>. ServerRuntime is - created simply by calling a - constructor:<programlisting language="java">ServerRuntime runtime = new ServerRuntime("com/example/cayenne-project.xml");</programlisting></para> - <para>The parameter you pass to the constructor is a location of the main project file. Location + created by calling a convenient builder: + <programlisting language="java">ServerRuntime runtime = ServerRuntime.builder() + .addConfig("com/example/cayenne-project.xml") + .build();</programlisting></para> + <para>The parameter you pass to the builder is a location of the main project file. Location is a '/'-separated path (same path separator is used on UNIX and Windows) that is resolved relative to the application classpath. The project file can be placed in the root package or in a subpackage (e.g. in the code above it is in "com/example" @@ -32,15 +34,13 @@ one ServerRuntime using it to create as many ObjectContexts as needed, access the Dependency Injection (DI) container and work with other Cayenne features. Internally ServerRuntime is just a thin wrapper around the DI container. Detailed features of the - container are discussed in "Customizing Cayenne Runtime" chapter. Here we'll just show - an example of how an application might replace a default implementation of a built-in - Cayenne service (in this case - QueryCache) with a different - class:<programlisting language="java">public class MyExtensionsModule implements Module { - public void configure(Binder binder) { - binder.bind(QueryCache.class).to(EhCacheQueryCache.class); - } -}</programlisting><programlisting language="java">Module extensions = new MyExtensionsModule(); -ServerRuntime runtime = new ServerRuntime("com/example/cayenne-project.xml", extensions);</programlisting></para> + container are discussed in <link linkend="customizing-cayenne-runtime">"Customizing Cayenne Runtime"</link> chapter. Here we'll just show + an example of how an application might turn on external transactions:<programlisting language="java">Module extensions = binder -> + ServerModule.contributeProperties(binder).put(Constants.SERVER_EXTERNAL_TX_PROPERTY, "true"); +ServerRuntime runtime = ServerRuntime.builder() + .addConfig("com/example/cayenne-project.xml") + .addModule(extensions) + .build();</programlisting></para> <para>It is a good idea to shut down the runtime when it is no longer needed, usually before the application itself is shutdown: <programlisting language="java">runtime.shutdown();</programlisting>When a runtime object has the same scope as the application, this may not be always @@ -52,14 +52,13 @@ ServerRuntime runtime = new ServerRuntime("com/example/cayenne-project.xml", ext <title>Merging Multiple Projects</title> <para>ServerRuntime requires at least one mapping project to run. But it can also take multiple projects and merge them together in a single configuration. This way different parts of - a database can be mapped independenlty from each other (even by different software + a database can be mapped independently from each other (even by different software providers), and combined in runtime when assembling an application. Doing it is as easy - as passing multiple project locations to ServerRuntime constructor:</para><programlisting language="java">ServerRuntime runtime = new ServerRuntime(new String[] { - "com/example/cayenne-project.xml", - "org/foo/cayenne-library1.xml", - "org/foo/cayenne-library2.xml" - } -);</programlisting> + as passing multiple project locations to ServerRuntime builder:</para><programlisting language="java">ServerRuntime runtime = ServerRuntime.builder() + .addConfig("com/example/cayenne-project.xml") + .addConfig("org/foo/cayenne-library1.xml") + .addConfig("org/foo/cayenne-library2.xml") + .build();</programlisting> <para>When the projects are merged, the following rules are applied:<itemizedlist> <listitem> <para>The order of projects matters during merge. If there are two conflicting http://git-wip-us.apache.org/repos/asf/cayenne/blob/c4e75227/docs/docbook/getting-started/src/docbkx/object-context.xml ---------------------------------------------------------------------- diff --git a/docs/docbook/getting-started/src/docbkx/object-context.xml b/docs/docbook/getting-started/src/docbkx/object-context.xml index 0996f6b..d17b64a 100644 --- a/docs/docbook/getting-started/src/docbkx/object-context.xml +++ b/docs/docbook/getting-started/src/docbkx/object-context.xml @@ -50,8 +50,9 @@ import org.apache.cayenne.configuration.server.ServerRuntime; public class Main { public static void main(String[] args) { - ServerRuntime cayenneRuntime = new ServerRuntime( - "cayenne-project.xml"); + ServerRuntime cayenneRuntime = ServerRuntime.builder() + .addConfig("cayenne-project.xml") + .build(); ObjectContext context = cayenneRuntime.newContext(); } }</programlisting></para>
