Tapis Sample Web Application Notes
==================================

Introduction
-----------
This sample web application can be used as a skeleton or prototype for actual Tapis web services.

The prototype integrates the following facilities:

    1. JAX-RS to implement REST endpoints.
    2. JAX-RS and servlet filters.
    3. Swagger to generate openapi json and yaml dynamically and at compile time.
    4. Logback for logging.
    5. Buildnumber maven plugin to capture git information at compile time.
    6. Flyway to create the tapis database and schema.
    7. Hikari for database connection pooling.
    8. io.jsonwebtoken for JWT processing.
    9. Aloe support for parameter parsing, email clients, threadlocal management, 
       UUIDs, etc. 
    
The sample web application packages its front-end (tapis-securityapi) and its backend 
(tapis-securitylib) separately to cleanly separate concerns.


Initialize the Tapis Database
-----------------------------
Use the utilities in tapis-migrate to create the Tapis database and its schema.  These
will create the sample_tbl that the sample web application uses.  See the README file 
in the tapis-migrate project for details.


Server Usage
------------
Web applications can be controlled using these environment variables:

tapis.envonly.allow.test.query.parms - allow test-only values sent as query parameters
tapis.envonly.jwt.optional - set to true to skip jwt processing
tapis.envonly.keystore.password - password to unlock jwt private signing key
tapis.envonly.skip.jwt.verify - set to true to skip jwt signature verification
tapis.request.logging.filter.prefixes - set url prefixes that log each request

See the TapisEnv class for an explanation of how to use these parameters and for the
complete listing of all possible Tapis parameters.  For example, to not require a jwt
in a request and to log all requests, set the following parameters when starting the 
server:
 
        tapis.envonly.jwt.optional = true
        tapis.request.logging.filter.prefixes = /tapis-sampleapi/v3.  
        
Note that if jwt content is required to execute requests, that information can be passed 
in request query parameters when tapis.envonly.allow.test.query.parms = true.

The sample web application is packaged as a WAR file.  Configure your web application
server, such as Tomcat, with the sample.war file.  Start your web application server 
after setting the above environment variables to control the sample web application.


Client Usage
------------
*** From Browser, enter these urls to execute application endpoints:

- Show index.html
    http://localhost:8080/c
    
- Run GET on hello method
    http://localhost:8080/README/v3/hello
    
*** From Browser, enter these urls to generate the openapi definition of the sample interface:

http://localhost:8080/security/v3/openapi.json
http://localhost:8080/security/v3/openapi.yaml


Creating from Scratch in Eclipse
--------------------------------
There are many paths to creating a project in Eclipse, but only some of them work for a given
application.  Our web application uses JAX-RS, so the ordering of actions during creation is 
critical.  Here's one recipe that works.

1. Create a new maven project with no archetype.
    - Edit pom.xml to make it look like the one in tapis-sampleapi.
    
2. Right click the project name in the Navigator.
    - Select Properties->Project Facets
    - Click the "convert to a facets project" link.
    - Select the JavaScript, Dynamic Web Module, JAX-RS facets in addition to the Java
        - Java -> version 12 or higher
        - Dynamic Web Module -> version 4.0 or higher
        - JAX-RS -> version 2.1 or higher 
    - Save
    
3. Right click the project name in the Navigator.
    - Select Properties->Deployment Assembly
    - Press Add
    - Select Maven Dependencies
    - Save
    
    Eclipse looks in the src/main/webapp/webapp directory for WEB-INF, index.html, etc.  
    Maven also defaults to this behavior.  Put non-code, non-resource content you want to 
    be part of the web application in that directory.
    
4. Make sure the web.xml is in WebContent/WEB-INF references the Jersey servlet.

5. Create an index.html file in WebContent directory.

6. The context root will be tapis-sampleapi by default.  Change the context by right 
   clicking the project name, then Properties->Web Project Settings and setting the 
   Context Root.
    - Making the context root and the war file name (finalName in pom) the same will 
      probably make life easier.