Google App Engine supports two kinds of application. The traditional kind is what I'll call a servlet app - a standard, Java Servlet application. It may contain multiple servlets and filters, but everything is in one WAR directory. Servlets can communicate with each other using several techniques, including direct method invocation, or using System properties to pass information, etc. The key point is that they need not send each other HTTP messages in order to cooperate.
The other kind of application, which I will call a service-based, or just services app, assembles one or more servlet apps into an application. Each servlet app is called a service (formerly: module), and functions as a micro-service in the assembled application. Such microservices collaborate via HTTP.
See Microservices Architecture on Google App Engine, Service: The building blocks of App Engine, and Configuration Files for more information.
boot-gae makes it easy to develop service-based applications, using the same code as for servlet applications. To build a service, do this (from the root of the service project):
$ boot gae/build -s
The -s (--service) switch tells boot-gae to build a service; the result will be placed in target/<servicename>. Building a service, unlike building a servlet app, will generate a jar file for the service. Install this:
$ boot install -f target/<servicename>/<service-jar-file-name>.jar
Do this for each service. Then, from the root directory of the service-based app, run the assemble task:
$ boot gae/assemble
To run the assembled app, use gae/run. The two commands can be combined:
$ boot gae/assemble gae/run
To interactively develop a service running in a services app, change to the service's root directory and run
$ boot gae/monitor -s
Now when you edit your service's code, the changes will be propagated to the assembled service-based app, where they will be loaded on page refresh.
How It Works
The service components and the services app must be correctly configured for this to work, of course. Each service component must include a :gae map in its build.boot file; it looks like this:(set-env!
:gae {:app-id "microservices-app"
:version "v1"
:module {:name "greeter"
:app-dir (str (System/getProperty "user.home")
"/boot/boot-gae-examples/standard-env/microservices-app")}}
...)
The :version string must conform to the GAE rules: The version identifier can contain lowercase letters, digits, and hyphens. It cannot begin with the prefix "ah-" and the names "default" and "latest" are reserved and cannot be used...Version names should begin with a letter, to distinguish them from numeric instances which are always specified by a number (see appengine-web.xml Reference).
The :app-dir string must be the path of the service-based app's root directory.
The :name string will be used (by gae/monitor -s) to construct the path of the service in its WAR directory in the services app; in this case, the result will will be
$HOME/boot/boot-gae-examples/standard-env/microservices-app/target/greeter
The gae/monitor -s task will copy source changes to this directory.
The services app must also include the :gae map in its build.boot file, but without the :module entry. In addition, the component services must be included in the :checkouts vector; for example:
:checkouts '[[tmp.services/main "0.2.0-SNAPSHOT" :module "default" :port 8083]
[tmp/greeter "0.1.0-SNAPSHOT" :module "greeter" :port 8088]
[tmp/uploader "0.1.0-SNAPSHOT" :module "uploader" :port 8089]]
The first service listed will be the default service; it must be named "default". The :module string here must match the :module :name string of the service's build.boot.
WARNING: this will change, so that service components will be listed in :dependencies.
Finally, the services app must contain a services.edn file, which looks like this:
{:app-id "boot-gae-greetings"
;; first service listed is default service
:services [{:service "default"}
{:service "greeter"}
{:service "uploader"}]}
WARNING: this will change. We have all the information needed to assemble the app in build.boot, so this edn file is not needed.
See standard environment examples for working demos.
Previous article: Building Clojure Apps on Google App Engine with boot-gae
Next article: boot-gae: Interactive Clojure Development on Google App Engine
No comments:
Post a Comment