Interface SpringBootIntegration

Integration with Spring Boot

Note, this section is specifically about integrating with Spring Boot. If you are looking for information about integrating with the traditional Spring framework, read the Integration with Spring article

Overview

Spring Boot is a popular technology for packaging entire webapps - including all config, all dependencies, and even the servlet engine itself - into a single standalone JAR file that can be executed with a simple "java -jar" command. SmartGWT integrates with Spring Boot, and Isomorphic provides installer scripts that automate the creation of working Spring Boot starter projects. This article describes those scripts and how to use them.

Available starter artifacts

Whether you use the creation scripts mentioned below, or set up a project manually, the starter artifact you declare as a dependency in your pom.xml determines which server-side capabilities are included. The following starter artifacts are available:

smartgwt-spring-boot-starter ? the default starter, and the one used by the Hello World script. Includes SmartGWT with its full SQL subsystem, making it the right choice for the majority of applications.

smartgwt-spring-boot-starter-jpa-hibernate ? adds Isomorphic's JPA and Hibernate integration layers on top of the default SmartGWT starter (the base starter is a transitive dependency, so you only need to declare this one). Use this if you want JPA or Hibernate support in addition to the built-in SQL subsystem. If you started from the Hello World app and subsequently decide you want JPA or Hibernate, simply replace smartgwt-spring-boot-starter with this artifact in your pom.xml.

smartgwt-spring-boot-starter-no-storage ? removes the SQL subsystem from the default starter. Intended only for applications with entirely custom storage requirements, or for pure-client use cases where no server-side data operations are needed.

Starter projects

Two categories of Spring Boot starter project are available:

Hello World ? a minimal but complete project that demonstrates the full stack working correctly: a browser page containing a SmartGWT ListGrid populated with country data read from a SQL database. The installer script prompts for your SmartGWT version, build date, license type and project coordinates, installs the required framework artifacts into your local Maven repository via the isc-maven-plugin, then generates the project, builds it with Maven, and optionally starts it. The generated project is placed as a new subdirectory of whatever directory you run the script from.

SmartGWT Showcase ? a complete, pre-built project containing hundreds of live SmartGWT examples covering data binding, grids, trees, forms, charts, drag-and-drop, AI integration, and much more. A script downloads the Showcase source archive, builds it with Maven, and optionally starts it.

Prerequisites

All scripts require the following prerequisites to be in place before you run them. The scripts themselves will check for each of these and report a clear error if anything is missing:

• Java 17 or later. The java executable must be on your PATH. Downloads are available from Adoptium and other providers
• Maven 3.9.2 or later. The mvn executable must be on your PATH. Download from maven.apache.org
• Smart GWT login credentials in your Maven settings.xml file (~/.m2/settings.xml on Linux/macOS, %USERPROFILE%\.m2\settings.xml on Windows). See item [2] on the Maven plugin configuration page for the required settings.xml format. The scripts check for the presence of a smartclient-developer profile and warn if it is not found
• curl and unzip ? required by the Showcase installer script only, to download and unpack the Showcase source archive. Both are pre-installed on macOS; Linux users can install them via their distribution's package manager. On Windows, curl is built into Windows 10 / Server 2019 and later; zip extraction is handled by the built-in tar command (also Windows 10 / Server 2019 and later)

Why custom installer scripts rather than Spring Initializr?

Spring Initializr is the standard mechanism for bootstrapping new Spring Boot projects, but it is limited to artifacts published in the Spring and Maven Central ecosystems. SmartGWT artifacts are bundled inside the SDK packages downloadable from the Isomorphic website and are not published to Maven Central; they must first be extracted and installed into your local .m2 repository using the isc-maven-plugin ? a step that Initializr has no knowledge of and cannot perform.

Beyond that initial installation step, there are further reasons why Initializr is not the right tool here. A SmartGWT Spring Boot project must use Isomorphic's own smartgwt-spring-boot-starter-parent as its Maven parent POM rather than Spring's spring-boot-starter-parent; Initializr always generates a project rooted at Spring's parent and there is no way to change this through the UI. For SmartGWT specifically, the project also requires a GWT module descriptor, a GWT entry-point class, and correct configuration of the isomorphicDir and isomorphicPathRootRelative settings that tie the compiled GWT output to SmartGWT's server-side servlets ? none of which Initializr knows anything about.

The installer scripts handle all of these steps end-to-end: they install the framework artifacts via the isc-maven-plugin, generate a correctly structured project with the right parent POM and all required configuration files, and build it with Maven in a single automated workflow.

Finally, this dependency on the isc-maven-plugin also means that Maven is the only supported build tool. We do not currently provide an equivalent plugin for Gradle or any other package manager, so projects must be Maven-based.

SmartGWT Hello World starter

Linux / macOS

  
 curl -O https://smartclient.com/spring-boot/create-smartgwt-boot-app.sh   chmod +x
 create-smartgwt-boot-app.sh   ./create-smartgwt-boot-app.sh

Windows

Download from https://smartclient.com/spring-boot/create-smartgwt-boot-app.bat and run from a Command Prompt:

  
 create-smartgwt-boot-app.bat

What the script does

The prompts are the same as for the Smart GWT Hello World script above, with one addition:

• GWT module name ? the value used for the rename-to attribute in the GWT module descriptor, and consequently the URL path prefix for the compiled application (e.g. a module name of myapp means the GWT bootstrap script is served from /myapp/myapp.nocache.js). Defaults to the project name lowercased

After confirming, the script installs framework artifacts, generates all project files including the GWT module descriptor and entry-point class, runs mvn clean package (which includes GWT compilation), and offers to start the application. GWT compilation can take a few minutes on first build. Once running, open http://localhost:8080 to see the result.

SmartGWT Showcase

The SmartGWT Showcase is a pre-built Spring Boot project containing hundreds of live examples. Unlike the Smart GWT Showcase, it cannot be embedded inside a Maven starter artifact. This is because SmartGWT applications are written in Java and must be GWT-compiled ? the compilation step processes your Java source code and generates JavaScript, and it runs as part of your own Maven build. There is no way to pre-compile that JavaScript into a generic, reusable starter JAR because the output is specific to the application's GWT module configuration and entry-point class. The Showcase is therefore distributed as a source archive that you download and build locally; the installer script automates this entirely.

Linux / macOS

   curl -O
 https://smartclient.com/spring-boot/install-smartgwt-showcase.sh   chmod +x
 install-smartgwt-showcase.sh   ./install-smartgwt-showcase.sh

Windows

Download from https://smartclient.com/spring-boot/install-smartgwt-showcase.bat and run from a Command Prompt:

  
 install-smartgwt-showcase.bat

What the script does

The script prompts for SmartGWT version, build date and license only ? no project coordinates are needed since the project structure comes from the downloaded archive. It will then:

1. Install the SmartGWT framework artifacts into your local Maven repository via the isc-maven-plugin
2. Warn you that it is about to download and unzip a file into the current directory, and give you the opportunity to cancel or to confirm that an existing SmartGWTBootShowcase directory can be overwritten
3. Download the Showcase source archive and unzip it, creating a SmartGWTBootShowcase subdirectory of the current directory
4. Run mvn clean package inside that directory ? this includes GWT compilation, which will take a few minutes on first build
5. Report the path to the built jar and offer to start it immediately

Once running, open http://localhost:8080 to browse the Showcase.

The demo database

Both of the starter projects ? Hello World and Showcase ? use an in-memory HSQLDB database, populated on startup with Isomorphic's standard set of demo data. This is a deliberate choice: because a Spring Boot application runs from inside a JAR file, it cannot safely assume that a writable filesystem location exists at a predictable path, so a self-contained in-memory database is the most portable default. The trade-off is that any changes you make to the data are not persisted ? the database is re-created fresh each time the application starts. Before doing any real development you should switch to a persistent database, as described in the Project structure for further development section below.

Project structure for further development

Once the Hello World app is working, you can use it as a base for further development:

• Remove the spring.boot.import.demo.database: true line from server.properties and instead add settings to configure access to a real database, as discussed in the SQL database settings article. For example, to connect to a local PostgreSQL database:

     sql.myDatabase.database.type: postgresql  
   sql.myDatabase.driver.serverName: localhost   sql.myDatabase.driver.portNumber: 5432  
   sql.myDatabase.driver: org.postgresql.Driver   sql.myDatabase.driver.databaseName:
   OrderProcessing   sql.myDatabase.driver.name: PostgreSQL   sql.myDatabase.driver.driverName:
   postgresql   sql.myDatabase.interface.type: driverManager   sql.myDatabase.driver.schema:
   public   sql.myDatabase.driver.user: myDBUser   sql.myDatabase.driver.password:
   myDBUserPassword   sql.myDatabase.interface.credentialsInURL: true   sql.defaultDatabase:
   myDatabase 

• Add your server-side Java logic under src/main/java/
• Add uncompiled assets that should be looked up from the classpath (configuration files for Hibernate, Log4j, etc.) under src/main/resources/ ? that directory becomes the classpath root at runtime
• Add your client-side assets under src/main/resources/static/ ? Spring Boot treats that directory specially, presenting it as the web root to the client side of your webapp. This is also the place to put non-compiled server-side assets that should be looked up from the webroot, such as .ds.xml files in a shared/ds/ subdirectory. Ordinarily Spring Boot does not make the static/ directory visible from the server side, but Smart GWT adds this functionality because it is needed in order to maintain compatibility with regular, non-Boot Smart GWT application structure

Spring Boot and Smart GWT skins

In a Spring Boot app, the framework skins/ directory - from which Smart GWT reads all the CSS and media assets required to implement a skin (aka theme) such as Tahoe or Shiva - is by default hidden away in a nested JAR inside the app's fat JAR. We can still read skin assets in this scenario as long as we know the file name we want (which we usually do), but there is no reliable way to iterate over a directory's contents to discover the names of files. This means that Smart GWT's Skin Editor - which tries to query the skins directory for a list of existing skins - does not work out of the box. To make it work, you must move the skins/ directory out of the framework JAR and into a real filesystem location, and then change the skinsDir property in your server.properties file to point at the new location.

The Smart GWT servlets

Smart GWT ships with a number of servlets providing server-side functionality. By default, the following servlets are mapped and available to your application, at the same URL as with the regular non-Boot framework

• IDACall at /isomorphic/IDACall/*
• RESTHandler at /isomorphic/RESTHandler/*
• HttpProxy at /isomorphic/HttpProxy
• DataSourceLoader at /isomorphic/DataSourceLoader
• ScreenLoaderServlet at /isomorphic/ScreenLoader
• ProjectLoaderServlet at /isomorphic/ProjectLoader

Additionally, the FileDownload servlet is mapped to the same URLs as in the regular, non-Boot framework, to provide compression and caching for framework code and skin assets. The Init servlet is not used; initialization logic is called from a Spring Boot Component, SmartClientSpringBootServletContextInitializer

Removing and Customizing servlet mappings

Changing Smart GWT's default servlet mappings is a fairly common requirement

• You may wish to remove an unused mapping - for example, if you have no intention of supporting REST requests, there is no need for RESTHandler
• You may wish to override one of the Smart GWT servlets with your own subclass - for example, customers sometimes use their own IDACall subclass to add things like custom request logging

However, Spring Boot places all configuration in code, so changing a framework servlet mapping is not just a case of changing a web.xml entry as it would be in a regular servlet container environment. Instead, you must do one of the following:

To remove a framework servlet mapping: Set the applicable property or properties from the list below to false in your Spring Boot application.properties or application.yml file:

• smartclient.idacall-servlet.enabled - note, IDACall provides access to the Smart GWT server framework and is thus required in any meaningful application that uses the server framework, unless you are accessing it purely via REST
• smartclient.resthandler-servlet.enabled - if you do not need REST support
• smartclient.datasourceloader-servlet.enabled - if you do not want to load DataSource definitions from the server (note, you nearly always DO want to load dataSources from the server; do not switch this servlet off unless you have a good reason)
• smartclient.projectloader-servlet.enabled - if you do not need support for loading Reify projects into your application
• smartclient.screenloader-servlet.enabled - if you do not need support for loading Reify screens into your application
• smartclient.httpproxy-servlet.enabled - if you do not need HTTP proxy support
• smartclient.filedownload-servlet.enabled - if you do not want to use Smart GWT's built-in support for serving framework assets compressed and with caching headers

To customize a framework servlet mapping: Smart GWT's Spring Boot servlet configuration looks for Spring Beans with special names; if any of those beans exist, it will not map the corresponding base servlet. For example, to customize IDACall, create your own implementation (probably by extending the Isomorphic version), then create a Spring Bean to represent it and map it with a ServletRegistrationBean, like this:

   @Bean(name = "CustomIDACallServlet")  
 public ServletRegistrationBean<MySuperIDACallSubclass> CustomIDACallServlet() {     
 return new ServletRegistrationBean<>(new MySuperIDACallSubclass(),
 "/isomorphic/IDACall/*");   } 

The "special names" to use for your custom bean(s) to inhibit mapping for the base servlet(s) follow a predictable and fairly obvious pattern, and are as follows:

Base servlet	Custom Spring Bean name
IDACall	CustomIDACallServlet
RESTHandler	CustomRESTHandlerServlet
DataSourceLoader	CustomDataSourceLoaderServlet
ProjectLoaderServlet	CustomProjectLoaderServlet
ScreenLoaderServlet	CustomScreenLoaderServlet
HttpProxy	CustomHttpProxyServlet
FileDownload	CustomFileDownloadServlet