This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Java Web Applications

Through the Java Guest Application API ("Guest App API" for short), Apprenda allows hosted Java-based applications (packaged as WARs) to inspect the Apprenda environment and interact with it in a number of ways.  This allows a Developer to build applications that leverage the Apprenda Platform services to the degree appropriate to the application. A "guest application" is any application running on the Apprenda Platform as a "workload" that is not a part of the Platform itself. Apprenda supports Java guest application components in the form of Java Web Applications (WARs).

The basic use cases that the Guest App API supports:

  • Checking if the application is running inside of Apprenda, and checking whether various Application Service levels are enabled (e.g. Authentication, Authorization, and Multi-tenancy)
  • Retrieve the current User (assuming Authentication is enabled)
  • Retrieve the current Tenant's database connection information
  • Retrieve the current Tenant and Tenant-related information (profile, contact information)

The more advanced use cases allow for deeper integration of a guest application w/ the underlying Apprenda Platform :   

  • Retrieve the current application version and interact  with the application's Securable resources and Feature meters, as defined in the application deployment configuration (or manifest).
  • Retrieve and interact with the Entitlements and Entitlement Groups for the current Tenant.
  • Retrieve and interact with the Users and Roles for the current Tenant.
  • Retrieve the current set of Single Sign-On security claims provided by the Platform

 

Getting Started

1. Install the Apprenda SDK

2. Create a New Project:

  • Using your favorite IDE (e.g., NetBeans)

     
  • Using Maven directly:
mvn.bat -DarchetypeGroupId=org.codehaus.mojo.archetypes -DarchetypeArtifactId=webapp-jee5 -DarchetypeVersion=1.3 -DarchetypeRepository=http://repo.maven.apache.org/maven2 -DgroupId=apprenda -DartifactId=testwebapp2 -Dversion=1.0-SNAPSHOT -Dpackage=apprenda.testwebapp2 -Dbasedir=C:\\Users\\UserName\\Documents\\NetBeansProjects -Darchetype.interactive=false --batch-mode archetype:generate

3. Add the Java Guest App API dependency

Maven Dependency

<dependency>
     <groupId>com.apprenda</groupId>
     <artifactId>guestapp-api</artifactId>
     <version>6.0</version>
     <scope>provided</scope>
</dependency>

NOTE: The Guest App API is a 'provided' dependency; it should not be packaged with the WAR file and will be provided by the Platform at runtime.

If your artifacts are not housed in an enterprise repository for binary artifacts, the missing dependency can be added from the local machine.

  • Using NetBeans, right-click on the missing guestapp-api dependency and select the Manually install artifact option.  Browse to the guestapp-api.jar installed with the Apprenda SDK Java API files:

  • Using Maven Directly

Guest App API Dependency

mvn.bat -DartifactId=guestapp-api -DgroupId=com.apprenda -Dversion=6.0 -Dpackaging=jar -Dfile=C:\\Program Files (x86)\\Apprenda\\SDK\\Java API Files\\apprenda-guestapp-api.jar -DgeneratePom=false install:install-file

Usage

The developer / API documentation is available on Apprenda's API documentation site or at the site of your Apprenda SDK install inside of the apprenda-guestapp-api-javadoc.jar

To get started using the API, first retrieve the GuestAppContext from the ApprendaGuestApp factory:

import com.apprenda.guest.api.ApprendaGuestApp;
import com.apprenda.guest.api.GuestAppContext;
....
 
// in your own code
GuestAppContext guestCtx = ApprendaGuestApp.getContext();

Basic Use Cases

Inspecting Application Services

Check if the application is running on Apprenda and if any of the Application Services are enabled . Knowing the level of services provided by the Apprenda environment allows a Developer to determine what other functionalities of the Guest App API would be available (e.g. attempting to retrieve Roles or check Securable permissions when Authorization is not enabled doesn't make any sense).

import com.apprenda.guest.api.ApprendaGuestApp;
import com.apprenda.guest.api.GuestAppContext;
....
 
// in your own code
GuestAppContext guestCtx = ApprendaGuestApp.getContext();
 
boolean isRunningInApprenda =  guestCtx.isEnabled());
boolean isAuthEnabled =  guestCtx.isAuthenticationEnabled());
boolean isAuthzEnabled =  guestCtx.isAuthorizationEnabled());

Inspecting the current User, Tenant, and Database Connection information

Note that for multi-tenant applications, the Tenant retrieved from the GuestAppContext should not be cached, as each incoming request could be issued by a User belonging to a different Tenant. The database connection configuration is available to the guest application through the ConnectionConfig . The information contained there could be useful to manually query the database. Also note that, similar to the "Tenant" note, the connection information might vary from request to request as users from different Tenants access the application. For single-tenant applications, the information retrieved from the Tenant is the information belonging to the Development Team that publishes the application.

Further information on the properties of each class is available on the API documentation for ConnectionConfig , TenantProfile , User , Location, and LocationDetails

import com.apprenda.guest.api.ApprendaGuestApp;
import com.apprenda.guest.api.GuestAppContext;
import com.apprenda.guest.tenant.ConnectionConfig;
import com.apprenda.guest.tenant.TenantProfile;
import com.apprenda.guest.tenant.User;
import com.apprenda.guest.api.AppVersion;
import com.apprenda.guest.api.Tenant;
 
// in your code
GuestAppContext guestCtx = ApprendaGuestApp.getContext();
if (guestCtx.isEnabled()) {
     Tenant currTenant = guestCtx.getTenant();
     ConnectionConfig connConf = currTenant.getConnectionConfig();     
     
     if (guestCtx.isAuthenticationEnabled()) {
                         
         TenantProfile tenantProfile = currTenant.getProfile();
         
         User currUser = guestCtx.getUser();
         Location userContact =  currTenant.getUserContactInfo(currUser.getId());
         Iterable<Location> tenantLocations = currTenant.getLocations();
     }          
}

Advanced Platform Integration

Enabling the more advanced Apprenda service level on your application (e.g. Authorization or Multi-tenancy) allows your application to leverage Apprenda's advanced Entitlements, Security, and Feature functionality.

Securables, Users, and Roles

Securables are pieces of code that a Development Team has marked as governed by Apprenda’s access control system. A Securable resource can be  either statically defined in application configuration (Static Securable), or created at runtime (Runtime Securable). Securable resources can be secured by granting permissions to the resource to Users and Roles defined within the Platform.  Please see the Securing Your Application via Roles topic for information on how to incorporate Securables into your Java application.

Working with Features

Features are small, uniquely labeled blocks of application code that are intended to be metered; they are sections of code that perform some transaction that requires access control based on the defined subscription owned by the current runtime User. Please see the Features topic for information on how to incorporate Features into your Java application.

Entitlement Groups and Entitlement Group Collections

An Entitlement Group is the runtime representation of the plan/subscription assigned to a User that allows the User to access the application and specific application Features. The entitlement group provides the "glue" information between the User that the subscription is assigned to, the terms of the subscription (e.g. renewal, termination dates), and the source (e.g. plan, application version) of the subscription. Entitlement Groups are created based on how many "subscriptions" are assigned/purchased by a Tenant.

An EntitlementGroupCollection is a collection of identical Entitlement Groups that are assigned to the given Tenant. The Entitlement Group collection contains entitlement groups/subscriptions of the same type for the applications that a Tenant is assigned (or has purchased). For example, a Tenant would have an entitlement group collection of 10 entitlement groups of the "Basic" type if they purchased 10 Basic subscriptions. When a Tenant purchases or is assigned a subscription to a given plan of an application, the newly added entitlement groups are added to this entitlement group collection The entitlement group provides summary information about the subscriptions to a given plan

The Guest App API allows the application to retrieve information about the entitlement groups for this application:

if (guestCtx.isAuthorizationEnabled()) {
    Tenant currTenant = guestCtx.getTenant();
    
    // Retrieve all entitlement group collections for the current tenant
    Iterable<EntitlementGroupCollection> allEntitlementGroupCollections = currTenant.getEntitlementGroupCollections();
    // then list the subscriptions in the first entitlement group collection, assume that the first one is the Basic subscriptions
    EntitlementGroupCollection basicSubscriptionsGroup = allEntitlementGroupCollections.iterator().next();
    // let's see how many of these we still have available to assign to users
    int numAvailable = basicSubscriptionsGroup.getAvailable()
    // Get the first page of 10 results
    Iterable<? extends EntitlementGroup> firstTenBasicSubscriptions = currTenant.listEntitlementGroups(basicSubscription.getId(), new PagingParams(1,10));
}

Further details on the EntitlementGroupCollection and EntitlementGroup can be found in the Java Guest App API documentation.

Leveraging Additional Platform Features