Overlayed AppProvider
This {@link AppProvider} implementation can deploy either {@link WebAppContext}s or plain {@link ContextHandler}s that are assembled from a series of overlays:
- webapp
- The webapp overlay is a WAR file or docroot directory. The intent is that the WAR should be deployed to this AppProvider unchanged from how it was delivered. All configuration and extension should be able to be done in an overlay.
- template
- A template overlay is applied to a WAR file to configure it for all instances of the webapp to be deployed in the server(s)
- node
- A node overlay is applied to a template to configure it all instances of the template with node specific information (eg IP address, DB servers etc.).
- instance
- An instance overlay is applied to a node and/or template to configure it for a specific instance of the template (eg per tenant configuration).
Each overlays may provide the following files and subdirectories:
- WEB-INF/lib-overlay
- The lib-overlay directory can contain jars that are applied to a {@link URLClassLoader} that isavailable before any overlay.xml files are executed, so that classes from these jars may be used by the overlay.xml.
- WEB-INF/overlay.xml
- This {@link XmlConfiguration} formatted file must exist in the WEB-INF directory of an overlay and is used to configure a {@link ContextHandler} or {@link WebAppContext}. The overlay.xml from the template overlay can be used to instantiate the ContextHandler instance, so a derived class maybe used.
- WEB-INF/template.xml
- This {@link XmlConfiguration} formatted file if it exists in a template or node overlay, is applied to a shared instance of {@link TemplateContext}. Any ID's created in a template are available as ID's in overlay.xml for an instance.
- WEB-INF/webdefault.xml
- If present in an overlay, then the most specific version is passed to {@link WebAppContext#setDefaultsDescriptor(String)}. Typically this is set in the template overlay.
- WEB-INF/web-overlay.xml
- The web-overlay.xml file of an overlay is applied to a web application as with {@link WebAppContext#addOverrideDescriptor(String)}. This allows incremental changes to web.xml without totally replacing it (see webapp). Typically this is used to set init parameters.
- .
- This root directory contains static content that overlays the static content of the webapp or earlier overlays. Using this directory, files like index.html or logo.png can be added or replaced. It can also be used to replace files within WEB-INF including web.xml classes and libs.
Any init parameters set on the context, filters or servlets may have parameterized values, with the parameters including:
- ${overlays.dir}
- the root overlay scan directory as a canonical file name.
- ${overlay.webapp}
- the webapp name, same as {@link Webapp#getName()}.
- ${overlay.template}
- the template name, as {@link Template#getName()}.
- ${overlay.template.name}
- the template classifier, as {@link Template#getTemplateName()}.
- ${overlay.template.classifier}
- the template classifier, as {@link Template#getClassifier()()}.
- ${overlay.node}
- the node name, as {@link Node#getName()}.
- ${overlay.instance}
- the instance name, {@link Instance#getName()}.
- ${overlay.instance.classifier}
- the instance name, {@link Instance#getClassifier()()}.
- ${*}
- Any properties obtained via {@link #getConfigurationManager()}. {@link ConfigurationManager#getProperties()}
The OverlayedAppProvider will scan the "webapps", "templates", "nodes" and "instances" subdirectories of the directory configured with {@link #setScanDir(File)}. New webapps and overlays and modified files within the overlays will trigger hot deployment, redeployment or undeployment. The scan for modified files is restricted to only top level files (eg overlay.xml) and the files matching WEB-INF/*.xml WEB-INF/lib/ and WEB-INF/classes/*. The webapps/overlays may be directory structures or war/jar archives.
The filenames of the templates and instances are used to match them together and with a webapplication. A webapp may be named anyway, but it is good practise to include a version number (eg webapps/foo-1.2.3.war or webapps/foo-1.2.3/). A template for that webapplication must have a name that includes the template name and the war name separated by '=' (eg templates/myFoo=foo-1.2.3.jar or templates/myFoo=foo-1.2.3/). An instance overlay is named with the template name and an arbitrary instance name separated by '=' (eg instances/myFoo=instance1.jar instances/myFoo=instance2/ etc.).
If a template name does not include a webapp name, then the template is created as a ContextHandler instead of a WebAppContext (with the exact type being determined by overlay.xml).