
package com.smartgwt.client.docs;

/**
 * <h3>Integration with Spring Boot</h3>
 * <i>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  {@link
 * com.smartgwt.client.docs.SpringIntegration Integration with Spring} article</i>
 * <h3>Overview</h3> <P> <a href='https://spring.io/projects/spring-boot' target='_blank'>Spring
 * Boot</a> 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 "<code>java -jar</code>" 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. <P>
 * <h3>Available starter artifacts</h3> <P> Whether you use the creation scripts mentioned below,
 * or set up a project manually, the  starter artifact you declare as a dependency in your
 * <code>pom.xml</code> determines which  server-side capabilities are included.  The following
 * starter artifacts are available: <P>   <b><code>smartgwt-spring-boot-starter</code></b> ? 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. <P>
 * <b><code>smartgwt-spring-boot-starter-jpa-hibernate</code></b> ? 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
 * <code>smartgwt-spring-boot-starter</code> with this artifact in your <code>pom.xml</code>. <P>
 * <b><code>smartgwt-spring-boot-starter-no-storage</code></b> ? 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.  <P> <h3>Starter
 * projects</h3> <P> Two categories of Spring Boot starter project are available: <P> <b>Hello
 * World</b> ? a minimal but complete project that demonstrates the full stack working correctly:
 * a browser page containing a SmartGWT <code>ListGrid</code> 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 <a href='https://github.smartclient.com/isc-maven-plugin'
 * target='_blank'>isc-maven-plugin</a>, 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. <P>  <b>SmartGWT Showcase</b> ? 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.  <P> <h3>Prerequisites</h3> <P>
 * 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: <ul>
 * <li><b>Java 17 or later</b>.  The <code>java</code> executable must be on your
 * <code>PATH</code>.  Downloads are available from <a href='https://adoptium.net/'
 * target='_blank'>Adoptium</a> and other providers</li> <li><b>Maven 3.9.2 or later</b>.  The
 * <code>mvn</code> executable must be on your <code>PATH</code>.  Download from <a
 * href='https://maven.apache.org/download.cgi' target='_blank'>maven.apache.org</a></li>
 * <li><b>Smart GWT login credentials</b> in your Maven <code>settings.xml</code> file
 * (<code>~/.m2/settings.xml</code> on Linux/macOS, <code>%USERPROFILE%\.m2\settings.xml</code> on
 * Windows).  See item [2] on the <a
 * href='https://github.smartclient.com/isc-maven-plugin/examples/configuration.html'
 * target='_blank'>Maven plugin configuration page</a> for the required <code>settings.xml</code>
 * format.  The scripts check for the presence of a <code>smartclient-developer</code> profile and
 * warn if it is not found</li> <li><b>curl</b> and <b>unzip</b> ? 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, <code>curl</code> is built into Windows 10 / Server 2019 and later; zip extraction
 * is handled by the built-in <code>tar</code> command (also Windows 10 / Server 2019 and
 * later)</li> </ul> <P> <h3>Why custom installer scripts rather than Spring Initializr?</h3> <P>
 * <a href='https://start.spring.io' target='_blank'>Spring Initializr</a> 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 <code>.m2</code> repository using the
 * <code>isc-maven-plugin</code> ? a step that Initializr has no knowledge of and cannot perform.
 * <P> 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
 * <code>smartgwt-spring-boot-starter-parent</code> as its Maven parent POM rather than Spring's
 * <code>spring-boot-starter-parent</code>; 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 <code>isomorphicDir</code> and <code>isomorphicPathRootRelative</code>
 * settings that tie the compiled GWT output to SmartGWT's server-side servlets ? none of which
 * Initializr knows anything about.  <P> The installer scripts handle all of these steps
 * end-to-end: they install the framework artifacts via the <code>isc-maven-plugin</code>,
 * 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. <P> Finally, this
 * dependency on the <code>isc-maven-plugin</code> also means that <b>Maven is the only supported
 * build tool</b>.  We do not currently provide an equivalent plugin for Gradle or any other
 * package manager, so projects must be Maven-based. <P>  <P>  <h3>SmartGWT Hello World
 * starter</h3> <P> <b>Linux / macOS</b> <pre style="font-size:10px;background-color:#e7e7e7">  
 * curl -O https://smartclient.com/spring-boot/create-smartgwt-boot-app.sh   chmod +x
 * create-smartgwt-boot-app.sh   ./create-smartgwt-boot-app.sh</pre> <P> <b>Windows</b> <P>
 * Download from <a href='https://smartclient.com/spring-boot/create-smartgwt-boot-app.bat'
 * target='_blank'>https://smartclient.com/spring-boot/create-smartgwt-boot-app.bat</a> and run
 * from a Command Prompt: <pre style="font-size:10px;background-color:#e7e7e7">  
 * create-smartgwt-boot-app.bat</pre> <P> <b>What the script does</b> <P> The prompts are the same
 * as for the Smart GWT Hello World script above, with one addition: <ul> <li><b>GWT module
 * name</b> ? the value used for the <code>rename-to</code> attribute in the GWT module
 * descriptor, and consequently the URL path prefix for the compiled application (e.g. a module
 * name of <code>myapp</code> means the GWT bootstrap script is served from
 * <code>/myapp/myapp.nocache.js</code>).  Defaults to the project name lowercased</li> </ul>
 * After confirming, the script installs framework artifacts, generates all project files
 * including the GWT module descriptor and entry-point class, runs <code>mvn clean package</code>
 * (which includes GWT compilation), and offers to start the application.  GWT compilation can
 * take a few minutes on first build.  Once running, open <code>http://localhost:8080</code> to
 * see the result.  <P>  <h3>SmartGWT Showcase</h3> <P> 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. <P> <b>Linux / macOS</b> <pre
 * style="font-size:10px;background-color:#e7e7e7">   curl -O
 * https://smartclient.com/spring-boot/install-smartgwt-showcase.sh   chmod +x
 * install-smartgwt-showcase.sh   ./install-smartgwt-showcase.sh</pre> <P> <b>Windows</b> <P>
 * Download from <a href='https://smartclient.com/spring-boot/install-smartgwt-showcase.bat'
 * target='_blank'>https://smartclient.com/spring-boot/install-smartgwt-showcase.bat</a> and run
 * from a Command Prompt: <pre style="font-size:10px;background-color:#e7e7e7">  
 * install-smartgwt-showcase.bat</pre> <P> <b>What the script does</b> <P> 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: <ol> <li>Install the
 * SmartGWT framework artifacts into your local Maven repository via the
 * <code>isc-maven-plugin</code></li> <li>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 <code>SmartGWTBootShowcase</code> directory can be overwritten</li> <li>Download the
 * Showcase source archive and unzip it, creating a <code>SmartGWTBootShowcase</code> subdirectory
 * of the current directory</li> <li>Run <code>mvn clean package</code> inside that directory ?
 * this includes GWT compilation, which will take a few minutes on first build</li> <li>Report the
 * path to the built jar and offer to start it immediately</li> </ol> Once running, open
 * <code>http://localhost:8080</code> to browse the Showcase.  <P> <h3>The demo database</h3> <P>
 * Both of the starter projects ? Hello World and Showcase ? use an in-memory <a
 * href='https://hsqldb.org/' target='_blank'>HSQLDB</a> 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 <i>Project
 * structure for further development</i> section below. <P> <h3>Project structure for further
 * development</h3> Once the Hello World app is working, you can use it as a base for further
 * development:<ul> <li>Remove the <code>spring.boot.import.demo.database: true</code> line from
 * <code>server.properties</code> and instead add settings to configure access to a real database,
 * as discussed in the {@link com.smartgwt.client.docs.SqlSettings SQL database settings article}.
 * For example, to connect to a local PostgreSQL database: <pre
 * style="font-size:10px;background-color:#e7e7e7">   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 </pre></li> <li>Add your server-side Java logic under
 * <code>src/main/java/</code></li> <li>Add uncompiled assets that should be looked up from the
 * classpath (configuration files for Hibernate, Log4j, etc.) under
 * <code>src/main/resources/</code> ? that directory becomes the classpath root at runtime</li>
 * <li>Add your client-side assets under <code>src/main/resources/static/</code> ? 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 <code>.ds.xml</code> files in a <code>shared/ds/</code> subdirectory.
 * Ordinarily Spring Boot does not make the <code>static/</code> 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</li> </ul> <P> <h3>Spring
 * Boot and Smart GWT skins</h3> In a Spring Boot app, the framework <code>skins/</code> 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 {@link
 * com.smartgwt.client.docs.SkinEditor 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
 * <code>skins/</code> directory out of the framework JAR and into a real filesystem location, and
 * then change the <code>skinsDir</code> property in your <code>server.properties</code> file to
 * point at the new location. <P>  <P> <h3>The Smart GWT servlets</h3> <P> Smart GWT ships with a
 * number of {@link com.smartgwt.client.docs.ServletDetails 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<ul> <li><b>IDACall</b> at
 * <code>/isomorphic/IDACall/*</code></li> <li><b>RESTHandler</b> at
 * <code>/isomorphic/RESTHandler/*</code></li> <li><b>HttpProxy</b> at
 * <code>/isomorphic/HttpProxy</code></li> <li><b>DataSourceLoader</b> at
 * <code>/isomorphic/DataSourceLoader</code></li> <li><b>ScreenLoaderServlet</b> at
 * <code>/isomorphic/ScreenLoader</code></li> <li><b>ProjectLoaderServlet</b> at
 * <code>/isomorphic/ProjectLoader</code></li> </ul> Additionally, the <b>FileDownload</b> 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 <code>Init</code> servlet is not used;
 * initialization logic is called from a Spring Boot Component,
 * <code>SmartClientSpringBootServletContextInitializer</code> <P> <b>Removing and Customizing
 * servlet mappings</b> <P> Changing Smart GWT's default servlet mappings is a fairly common
 * requirement<ul> <li>You may wish to remove an unused mapping - for example, if you have no
 * intention of supporting REST requests, there is no need for <code>RESTHandler</code></li>
 * <li>You may wish to override one of the Smart GWT servlets with your own subclass - for
 * example, customers sometimes use their own <code>IDACall</code> subclass to add things like
 * custom request logging</li> </ul> <P> However, Spring Boot places all configuration in code, so
 * changing a framework servlet mapping is not just a case of changing a <code>web.xml</code>
 * entry as it would be in a regular servlet container environment.  Instead, you must do one of
 * the following: <P> <b>To remove a framework servlet mapping:</b> Set the applicable property or
 * properties from the list below to false in your Spring Boot <code>application.properties</code>
 * or <code>application.yml</code> file:<ul> <li>smartclient.idacall-servlet.enabled - note,
 * <code>IDACall</code> 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</li> <li>smartclient.resthandler-servlet.enabled - if you do not need REST
 * support</li> <li>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)</li>
 * <li>smartclient.projectloader-servlet.enabled - if you do not need support for loading  Reify
 * projects into your application</li> <li>smartclient.screenloader-servlet.enabled - if you do
 * not need support for loading Reify screens into your application</li>
 * <li>smartclient.httpproxy-servlet.enabled - if you do not need {@link
 * com.smartgwt.client.rpc.RPCManager#sendProxied HTTP proxy support}</li>
 * <li>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</li> </ul> <b>To
 * customize a framework servlet mapping:</b> 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 <code>IDACall</code>, 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: <pre
 * style="font-size:10px;background-color:#e7e7e7">   &#64;Bean(name = "CustomIDACallServlet")  
 * public ServletRegistrationBean&lt;MySuperIDACallSubclass&gt; CustomIDACallServlet() {     
 * return new ServletRegistrationBean&lt;&gt;(new MySuperIDACallSubclass(),
 * "/isomorphic/IDACall/*");   } </pre> 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: <P> <table><tr> <td style="background-color:black; color:white;">Base
 * servlet</td> <td style="background-color:black; color:white;">Custom Spring Bean name</td></tr>
 * <tr><td>IDACall</td><td>CustomIDACallServlet</td></tr>
 * <tr><td>RESTHandler</td><td>CustomRESTHandlerServlet</td></tr>
 * <tr><td>DataSourceLoader</td><td>CustomDataSourceLoaderServlet</td></tr>
 * <tr><td>ProjectLoaderServlet</td><td>CustomProjectLoaderServlet</td></tr>
 * <tr><td>ScreenLoaderServlet</td><td>CustomScreenLoaderServlet</td></tr>
 * <tr><td>HttpProxy</td><td>CustomHttpProxyServlet</td></tr>
 * <tr><td>FileDownload</td><td>CustomFileDownloadServlet</td></tr> </table>
 */
public interface SpringBootIntegration {
}
