Across Application Descriptor

On this page, you will:

Learn about Across Application and Module.
Learn what the Across Application Descriptor is.
Get some background on the relation between Across and Spring.

Application and Modules

Any Across application is made up of a number of Across modules. An Across module defines components and resources that together provide a set of functionality for your application. A single module can provide a complete user interface for your application or just a single service to integrate with a remote datastore.

The components that a module provides can be internal to that module, or they can be made available for other modules.

Across modules can depend on other modules. When an Across application starts it will first build a dependency tree of all modules and then start each module in the order determined by its dependencies.

The Across Application Descriptor defines:

the entry point of an Across application
which modules are present in the application
which components and related infrastructure are available to all modules of the application

The Across Application Descriptor is defined by the single class annotated with @AcrossApplication.

@AcrossApplication

An Across application can have exactly one class annotated with @AcrossApplication. This marks the class as the Across Application Descriptor.

@AcrossApplication( modules = {} ) (1)
public class DemoApplication
{
	public static void main( String[] args ) {  (2)
		SpringApplication.run( DemoApplication.class, args );
	}
}

1	`@AcrossApplication` annotation that defines which modules are present.
2	The Application Descriptor usually contains the Java `main` method for starting the entire application (as a Spring Boot app).

Adding a module

The @AcrossApplication has several attributes to define the initial application configuration.

The easiest way to add a module to your application is by specifying the unique module name in the modules attribute of @AcrossApplication. The AcrossWebModule dependency is automatically added to our sample project, but the module itself is not.

You can activate Across Web support by adding the module name to the list:

@AcrossApplication( modules = { AcrossWebModule.NAME } ) (1)
public class DemoApplication
{
	public static void main( String[] args ) {
		SpringApplication.run( DemoApplication.class, args );
	}
}

1	We use the `AcrossWebModule.NAME` constant to refer to the unique module name.

When restarting the application, you now see in the console output that the AcrossWebModule is also being bootstrapped.

---
AcrossContext: DemoApplication (AcrossContext-1)
Bootstrapping 3 modules in the following order:
1 - AcrossWebModule [resources: ]: class com.foreach.across.modules.web.AcrossWebModule (1)
2 - DemoApplicationModule [resources: demo]: class com.foreach.across.core.DynamicAcrossModule$DynamicApplicationModule
3 - AcrossContextPostProcessorModule [resources: AcrossContextPostProcessorModule]: class com.foreach.across.core.AcrossContextConfigurationModule
---

1	AcrossWebModule has been added to the application and will bootstrap first.

If you now go take your browser to http://localhost:8080 you will no longer see the generic Tomcat 404 page, but the whitelabel error page activated by Across Web support.

Across Web loads the Spring Boot whitelabel error page

Chapter Adding modules shows other ways to add modules to the Application Descriptor.

Apart from actual modules, the Application Descriptor also allows you to define additional application infrastructure as Spring beans.

Across applications and Spring Boot

Across applications execute as Spring Boot applications. If you are familiar with Spring Boot, @AcrossApplication is the equivalent of @SpringBootApplication.

The Across Application Descriptor is also a regular Spring @Configuration class. It can contain @Bean methods or define any other components. These components will then be available for all modules.

An Across application is made up of several Across modules. Every module is its own Spring ApplicationContext with the Across Application Descriptor providing a shared parent ApplicationContext.

This is different from most regular Spring Boot applications that only define a single ApplicationContext holding all components. Across encourages you to bundle components as much as possible in separate modules, as such you should limit the configuration of your Application Descriptor to the minimum required.

Because Across applications run on top of Spring Boot, most regular Spring libraries can be adapted to work in a multi-module Across application. Across applications also have some support for Spring Boot auto-configuration classes.

Embedded servlet container example

An example of the Spring Boot auto-configuration support is the embedded Tomcat webserver in our sample application. Because spring-boot-starter-tomcat is added as a Maven dependency, an embedded Tomcat will be automatically started when running the application.

...
INFO --- [  restartedMain] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat initialized with port(s): 8080 (http) (1)
INFO --- [  restartedMain] o.apache.catalina.core.StandardService   : Starting service [Tomcat] (2)
INFO --- [  restartedMain] org.apache.catalina.core.StandardEngine  : Starting Servlet Engine: Apache Tomcat/8.5.27
INFO --- [ost-startStop-1] o.a.c.c.C.[Tomcat].[localhost].[/]       : Initializing Spring embedded WebApplicationContext
...
INFO --- [  restartedMain] s.b.c.e.t.TomcatEmbeddedServletContainer : Tomcat started on port(s): 8080 (http) (3)
INFO --- [  restartedMain] com.example.demo.DemoApplication         : Started DemoApplication in 3.36 seconds (JVM running for 7.7) (4)

1	The embedded tomcat server is being initialized. By default, it will start the application on port 8080, this can also be configured using the `server.port` property.
2	The tomcat server is being started.
3	The tomcat server is fully started.
4	The application has fully started.

You can find more information on embedded servlet containers in the Spring Boot documentation.

Next step

Read about the application project structure.