You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2015/04/28 08:13:55 UTC
[2/2] isis git commit: ISIS-1133: command line parsing, updated README,
tidying up docs on BackgroundCommandExecution
ISIS-1133: command line parsing, updated README, tidying up docs on BackgroundCommandExecution
Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/a48eb1bf
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/a48eb1bf
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/a48eb1bf
Branch: refs/heads/ISIS-1133
Commit: a48eb1bf17983ee4de07b5fbbbf028a1e6607334
Parents: fb3edc9
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Tue Apr 28 07:13:46 2015 +0100
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Tue Apr 28 07:13:46 2015 +0100
----------------------------------------------------------------------
adocs/documentation/Gemfile | 3 +
adocs/documentation/Gemfile.lock | 6 ++
adocs/documentation/README.md | 92 ++++++++--------
adocs/documentation/monitor.rb | 107 ++++++++++++-------
.../_user-guide_background-execution.adoc | 93 +++++++++++++---
.../BackgroundCommandExecution.png | Bin 0 -> 26916 bytes
...ExecutionFromBackgroundCommandServiceJdo.png | Bin 0 -> 38373 bytes
adocs/template/document.html.erb | 18 ++++
8 files changed, 219 insertions(+), 100 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/Gemfile
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile b/adocs/documentation/Gemfile
index 28c87ac..7723995 100644
--- a/adocs/documentation/Gemfile
+++ b/adocs/documentation/Gemfile
@@ -13,3 +13,6 @@ gem 'tilt'
gem 'thread_safe'
gem 'coderay'
gem 'webrick'
+
+gem 'launchy', '~> 2.4.3'
+gem 'slop', '~> 4.1.0'
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/Gemfile.lock
----------------------------------------------------------------------
diff --git a/adocs/documentation/Gemfile.lock b/adocs/documentation/Gemfile.lock
index a29d581..7af60f8 100644
--- a/adocs/documentation/Gemfile.lock
+++ b/adocs/documentation/Gemfile.lock
@@ -1,12 +1,15 @@
GEM
remote: https://rubygems.org/
specs:
+ addressable (2.3.8)
asciidoctor (1.5.2)
celluloid (0.16.0)
timers (~> 4.0.0)
coderay (1.1.0)
ffi (1.9.8-x64-mingw32)
hitimes (1.2.2)
+ launchy (2.4.3)
+ addressable (~> 2.3)
listen (2.10.0)
celluloid (~> 0.16.0)
rb-fsevent (>= 0.9.3)
@@ -14,6 +17,7 @@ GEM
rb-fsevent (0.9.4)
rb-inotify (0.9.5)
ffi (>= 0.5.0)
+ slop (4.1.0)
thread_safe (0.3.5)
tilt (2.0.1)
timers (4.0.1)
@@ -27,7 +31,9 @@ PLATFORMS
DEPENDENCIES
asciidoctor
coderay
+ launchy (~> 2.4.3)
listen (~> 2.7)
+ slop (~> 4.1.0)
thread_safe
tilt
wdm (>= 0.1.0)
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/README.md
----------------------------------------------------------------------
diff --git a/adocs/documentation/README.md b/adocs/documentation/README.md
index 38b502e..0e4a930 100644
--- a/adocs/documentation/README.md
+++ b/adocs/documentation/README.md
@@ -44,32 +44,28 @@ Naming Conventions
For documents with inclusions, use '_' to separate out the logical hierarchy:
-<pre>
-xxx-xxx/xxx-xxx.adoc
- _xxx-xxx_ppp-ppp.adoc
- _xxx-xxx_qqq-qqq.adoc
- _xxx-xxx_qqq-qqq_mmm-mmm.adoc
- _xxx-xxx_qqq-qqq_nnn-nnn.adoc
-</pre>
+ xxx-xxx/xxx-xxx.adoc
+ _xxx-xxx_ppp-ppp.adoc
+ _xxx-xxx_qqq-qqq.adoc
+ _xxx-xxx_qqq-qqq_mmm-mmm.adoc
+ _xxx-xxx_qqq-qqq_nnn-nnn.adoc
Any referenced images should be in subdirectories of the `images` directory:
-<pre>
-xxx-xxx/images/.
- /ppp-ppp/.
- /qqq-qqq/.
- /mmm-mmm
- /nnn-nnn
-</pre>
+ xxx-xxx/images/.
+ /ppp-ppp/.
+ /qqq-qqq/.
+ /mmm-mmm
+ /nnn-nnn
And similarly any resources should be in the `resources` subdirectory:
-<pre>
-xxx-xxx/resources/.
- ppp-ppp/.
- qqq-qqq/.
- /mmm-mmm/
- /nnn-nnn/
-</pre>
+
+ xxx-xxx/resources/.
+ ppp-ppp/.
+ qqq-qqq/.
+ /mmm-mmm/
+ /nnn-nnn/
+
Build and Review (using Maven)
-----------------------
@@ -80,55 +76,57 @@ To build the documentation locally prior to release, use:
The site will be generated at `target/site/index.html`.
-
-Review
-------
-
-Then open the browser on [localhost:8000](http://localhost:8000/).
+You could then use a web server such as Python's SimpleHTTPServer to preview (so that all Javascript works correctly). However, instead we recommend using instant preview, described nex.
-Instant Preview (optional)
+Instant Rebuild (using Ruby)
---------------
+The ruby script, `monitor.rb` emulates the `mvn site` command, regenerating any changed Asciidoctor files to the relevant `target/site` directory. If any included files are changed then it rebuilds the parent (per the above naming convention).
+To setup:
-To build
+* download and install ruby 2.0.0, from [http://rubyinstaller.org/downloads/](rubyinstaller.org/downloads)
+* download devkit for the Ruby 2.0 installation, also from [http://rubyinstaller.org/downloads/](rubyinstaller.org/downloads). Then follow the [https://github.com/oneclick/rubyinstaller/wiki/Development-Kit](installation instructions) on their wiki
-download ruby 2.0.0
+> Note the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.
-* [http://rubyinstaller.org/downloads/](rubyinstaller.org/downloads)
+install:
-> the wdm gem (required to monitor the filesystem if running on Windows) is not currently compatible with Ruby 2.1.
+ gem install bundler
+ bundle install
-download and install devkit for the Ruby 2.0 installation:
+to run, typically just use:
-* [http://rubyinstaller.org/downloads/](rubyinstaller.org/downloads)
-* [https://github.com/oneclick/rubyinstaller/wiki/Development-Kit](Ruby DevKit installation)
+ ruby monitor.rb
-install:
+This will start monitoring all files under `src/main/asciidoc`, and start up a web server on port 4000 so you can review results.
- gem install bundler
- bundle install
+There are several other options, use `-h` flag for usage:
-run:
+ ruby monitor.rb -h
- ruby listen.rb
+which should print:
-To review, recommend running a Python server:
+ usage: monitor.rb [options]
+ -a, --all process all files
+ -x, --nomonitor do not monitor, just process all files then exit
+ -p, --port port (default: 4000)
+ -b, --browser launch browser
+ -h, --help help
- cd target/site
- python -m SimpleHTTPServer
+So, for example
+
+ ruby monitor.rb -a -b -p 9090
+will process all files before starting monitoring, start the web browser on port 9000, and will also automatically open up your default web browser at that port.
+
-Uses:
-*
Publish procedure
-----------------
-To publish the documentation at [Isis Site](http://isis.apache.org/) you have do the following steps:
-
-To publish to [staging server](http://isis.staging.apache.org/docs), run:
+To publish the documentation to the [ASF staging server](http://isis.staging.apache.org/docs), run:
mvn clean site-deploy
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/monitor.rb
----------------------------------------------------------------------
diff --git a/adocs/documentation/monitor.rb b/adocs/documentation/monitor.rb
index 36d2acf..b5cdb14 100644
--- a/adocs/documentation/monitor.rb
+++ b/adocs/documentation/monitor.rb
@@ -1,28 +1,40 @@
-#!/c/bin/Ruby200-x64/bin/ruby -w
-
require 'rubygems'
require 'pathname'
require 'fileutils'
require 'bundler/setup'
-
-#require 'launchy'
-
+require "slop"
+require 'launchy'
require 'webrick'
-#include Launchy
+Bundler.require(:default)
+
include WEBrick
+# to (try to) suppress some debugs
+$CELLULOID_DEBUG=false
+$CELLULOID_TEST=false
-Bundler.require(:default)
+#
+# parse cmd line args
+#
+opts = Slop.parse do |o|
+ o.bool '-a', '--all', 'process all files'
+ o.bool '-x', '--nomonitor', 'do not monitor, just process all files then exit'
+ o.int '-p', '--port', 'port (default: 4000)', default: 4000
+ o.bool '-b', '--browser', 'launch browser'
+ o.bool '-h', '--help', 'help'
+end
-#prime = false
+if opts.help? then
+ puts opts
+ exit
+end
+processAll = opts.all? || opts.nomonitor?
+port = opts[:port]
-# to suppress some debugs
-$CELLULOID_DEBUG=false
-$CELLULOID_TEST=false
#scriptDir = File.absolute_path File.dirname(__FILE__)
templateDir = File.absolute_path '../template'
@@ -70,10 +82,10 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,priming)
cmd = "asciidoctor #{regenerate} --backend html --eruby erb --template-dir '#{templateDir}' --destination-dir='#{targetRelDir}' -a imagesdir='' -a toc=right -a icons=font -a source-highlighter=coderay"
- #unless priming then
+ unless priming then
puts ""
puts "#{i}: #{cmd}"
- #end
+ end
system cmd
end
@@ -84,10 +96,10 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,priming)
cmd = "cp #{srcBase} #{targetRelDir}"
- #unless priming then
+ unless priming then
puts ""
puts "#{i}: #{cmd}"
- #end
+ end
system cmd
@@ -102,29 +114,35 @@ def process(file,srcBasePath,targetBasePath,templateDir,i,priming)
end
-puts ""
-puts ""
-puts ""
-puts "priming (processing all files)..."
-puts ""
-
-
#
-# priming: process all files
+# process all files
#
-files = Dir.glob("src/main/asciidoc/**/*")
-#if prime then
+if processAll then
+
+ files = Dir.glob("src/main/asciidoc/**/*")
+
+ puts ""
+ puts ""
+ puts ""
+ puts "processing all files..."
+ puts ""
+
files.each { |file|
absFile = File.absolute_path file
i = process absFile, srcBasePath, targetBasePath, templateDir, i, true
}
-#end
+end
+
+if opts.nomonitor? then
+ exit
+end
+
puts ""
puts ""
puts ""
-puts "now monitoring..."
+puts "monitoring..."
puts ""
@@ -132,7 +150,7 @@ puts ""
# then continue monitoring all directories
#
directories = Dir.glob("src/main/asciidoc/**/*/")
-listener = Listen.to(directories) do |modified, added, removed|
+fileListener = Listen.to(directories) do |modified, added, removed|
unless modified.length==0
modified.each { |file|
i = process file, srcBasePath, targetBasePath, templateDir, i, false
@@ -149,18 +167,33 @@ listener = Listen.to(directories) do |modified, added, removed|
}
end
end
-listener.start
+fileListener.start
-s = HTTPServer.new(:Port => 4000, :DocumentRoot => 'target/site')
+httpServer = HTTPServer.new(:Port => port, :DocumentRoot => 'target/site')
trap("INT"){
- s.shutdown
- listener.stop
+ httpServer.shutdown
+ fileListener.stop
}
-s.start
-#puts ""
-#puts "opening web browser @ http://localhost:4000/"
-#puts
-#Launchy.open("http://localhost:4000")
+
+if opts.browser? then
+
+ puts ""
+ puts "opening web browser @ http://localhost:#{port}/"
+ puts
+
+ Launchy.open("http://localhost:#{port}")
+else
+ puts ""
+ puts "open web browser @ http://localhost:#{port}/"
+ puts
+
+end
+
+
+
+httpServer.start
+
+
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
index 3221cde..0553de4 100644
--- a/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
+++ b/adocs/documentation/src/main/asciidoc/user-guide/_user-guide_background-execution.adoc
@@ -3,38 +3,99 @@
:_basedir: ../
:_imagesdir: images/
-IMPORTANT: TODO
+As well as supporting the Wicket viewer and Restful viewer for "online" access, Apache Isis also supports programmatic access. The API provided is low-level and allows code to interact very directly with the Isis metamodel and runtime. Howwever the <<WrapperFactory>> service could be used to enforce business rules if required.
+Typical use cases are to support batch execution or background scheduler execution (eg using http://quartz-scheduler.org[Quartz]) . It could also be used to run Isis as a service, or to integrate within a JMS/ESB messaging solutions.
-## JDO Implementation
+== AbstractIsisSessionTemplate
-The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of link:../../../../reference/non-ui/background-command-execution.html[BackgroundCommandExecution]. The intended use is for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz.org[Quartz]) to poll for `Command`s to be executed, and then execute them.
+The `AbstractIsisSessionTemplate` class (whose name is inspired by the Spring framework's naming convention for similar classes that query http://docs.spring.io/spring/docs/2.5.x/reference/jdbc.html#jdbc-JdbcTemplate[JDBC], http://docs.spring.io/spring/docs/2.5.x/reference/jms.html#jms-jmstemplate[JMS], http://docs.spring.io/spring/docs/2.5.x/reference/orm.html#orm-jpa-template[JPA] etc.) provides the mechanism to open up a 'session' within the Isis framework, in order to resolve and interact with entities.
-As you might imagine, this implementation queries for `Command`s persisted by the JDO implementations of link:../services/command-service-jdo.html[CommandService] and link:../services/background-command-service-jdo.html[BackgroundCommandService], using the `BackgroundCommandServiceJdoRepository`.
+The class itself is intended to be subclassed:
-The diagram below shows the inheritance hierarchy for this class:
+[source,java]
+----
+public abstract class AbstractIsisSessionTemplate {
-.Inheritance Hierarchy for `BackgroundCommandExecution`
-image::http://yuml.me/363b335f[width="600px"]
+ public void execute(final AuthenticationSession authSession, final Object context) { ... } //<1>
+ protected abstract void doExecute(Object context); // <2>
+ protected ObjectAdapter adapterFor(final Object targetObject) { ... }
+ protected ObjectAdapter adapterFor(final RootOid rootOid) { ... }
-[NOTE]
-====
-In 1.6.0 this implementation was released as part of `org.apache.isis.core:isis-module-command-jdo:1.6.0` and was also released as an http://github.com/isisaddons/isis-module-command[Isis addon] module.
+ protected PersistenceSession getPersistenceSession() { ... }
+ protected IsisTransactionManager getTransactionManager() { ... }
+ protected AdapterManager getAdapterManager() { ... }
+}
+----
+<1> `execute(...)` sets up the `IsisSession` and delegates to ...
+<2> `doExecute(...)`, the mandatory hook method for subclasses to implement.
+The passed object represents passes a context from the caller (eg the scheduler, cron job, JMS etc) that instantiated and executed the class.
+
+The `protected` methods expose key internal APIs within Isis, for the subclass to use as necessary.
+
+
+TIP: One notable feature of `AbstractIsisSessionTemplate` is that it will automatically inject any domain services into itself. Thus, it is relatively easy for the subclass to "reach into" the domain, through injected repository services.
-In 1.7.0+ only the http://github.com/isisaddons/isis-module-command[Isis addon] (non-ASF) implementation is released.
-====
-## Footnote
-NOTE: The diagrams on this page were created using http://yuml.me[yuml.me].
+== BackgroundCommandExecution
+
+The `BackgroundCommandExecution` class (a subclass of <<AbstractIsisSessionTemplate>>) is intended to simplify the execution of background ``Command``s persisted by way of the <<CommandService>> and the <<BackgroundCommandService>>.
+
+Its signature is:
+
+[source,java]
+----
+public abstract class BackgroundCommandExecution extends AbstractIsisSessionTemplate {
+ protected void doExecute(Object context) { ... }
+ protected abstract List<? extends Command> findBackgroundCommandsToExecute(); // <1>
+}
+----
+<1> `findBackgroundCommandsToExecute()` is a mandatory hook method for subclasses to implement.
+
+This allows for different implementations of the `CommandService` and `BackgroundCommandService` to persist to wherever.
+
+The diagram below shows the dependencies between these various classes:
+
+.Inheritance Hierarchy for `BackgroundCommandExecution`
+image::{_imagesdir}background-execution/BackgroundCommandExecution.png[width="400px"]
+[TIP]
+====
[source]
-.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f]):
+.DSL (http://yuml.me/edit/363b335f[yuml.me/363b335f])
----
[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
[BackgroundCommandExecution]^-[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]
[BackgroundCommandExecutionFromBackgroundCommandServiceJdo]->injected[BackgroundCommandServiceJdoRepository|findBackgroundCommandsNotYetStarted()]
-----
\ No newline at end of file
+----
+====
+
+
+
+## BackgroundCommandExecutionFromBackgroundCommandServiceJdo
+
+NOTE: this class is part of http://isisaddons.org/isis-module-command[Isis addons Command Module] (not ASF)
+
+The `BackgroundCommandExecutionFromBackgroundCommandServiceJdo` is a concrete subclass of <<BackgroundCommandExecution>>, the intended use being for the class to be instantiated regularly (eg every 10 seconds) by a scheduler such as http://quartz-scheduler.org[Quartz]) to poll for ``Command``s to be executed, and then execute them.
+
+This implementation queries for ``Command``s persisted by the http://isisaddons.org/isis-module-command[Isis addons Command Module]'s implementations of <<CommandService>> and <<BackgroundCommandService>> using the `BackgroundCommandServiceJdoRepository`.
+
+The diagram below shows the inheritance hierarchy for this class:
+
+.Inheritance Hierarchy for `BackgroundCommandExecutionFromBackgroundCommandServiceJdo`
+image::{_imagesdir}background-execution/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png[width="500px"]
+
+[TIP]
+====
+[source]
+.DSL (http://yuml.me/edit/25343da1[yuml.me/25343da1]):
+----
+[AbstractIsisSessionTemplate|#doExecute()]^-[BackgroundCommandExecution|#findBackgroundCommandsToExecute()]
+[BackgroundCommandExecution]->injected[BookmarkService|lookup()]
+[BackgroundCommandExecution]->injected[CommandContext|setCommand()]
+----
+====
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecution.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecution.png b/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecution.png
new file mode 100644
index 0000000..5cefae3
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecution.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png b/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png
new file mode 100644
index 0000000..0c026fb
Binary files /dev/null and b/adocs/documentation/src/main/asciidoc/user-guide/images/background-execution/BackgroundCommandExecutionFromBackgroundCommandServiceJdo.png differ
http://git-wip-us.apache.org/repos/asf/isis/blob/a48eb1bf/adocs/template/document.html.erb
----------------------------------------------------------------------
diff --git a/adocs/template/document.html.erb b/adocs/template/document.html.erb
index 6106875..2ff9092 100644
--- a/adocs/template/document.html.erb
+++ b/adocs/template/document.html.erb
@@ -119,6 +119,24 @@
/*width: 20em;*/
width: 25em;
}
+
+ h2 {
+ margin-top: 50px;
+ }
+ h3 {
+ margin-top: 30px;
+ }
+ h4,h5 {
+ margin-top: 20px;
+ }
+
+ .admonitionblock.tip > table td.content {
+ color: #10B061;
+ }
+
+ .imageblock img {
+ margin-bottom: 10px;
+ }
</style>
</head>