This is documentation for the current major version Apprenda 7.
Documentation for older versions are also available.

Eclipse Plugin

Introduction 

This page describes the functionality of the Apprenda Eclipse plugin.

Installation

  1. Download Eclipse IDE for Java EE Developers ( Kepler v. 4.3.1) from http://www.eclipse.org/downloads/; unzip it into a local folder and start it. Note that there are other distributions/bundles but they do not contain the features that a typical Java web developer would need.
  2. Go to Help -> Install New Software, Click the Add button to add a a new Software Site / Repository to allow the installation and update of the plugin. Adding this Software Site will allow the you to be notified when Apprenda releases updates and will update the plugin with the new version.
  3. Set the Location to https://raw.githubusercontent.com/Apprenda/eclipse-plugin/releases/updates/current
  4. Step through the installation wizard, confirming the installation of the plugin. Allow Eclipse to restart.
  5. When Eclipse starts, there will be a link on the overview page leading to the Apprenda SDK intro documentation; this is the first indication that the plugin has installed successfully.

Usage/Features

Configure Apprenda Cloud

The Apprenda Cloud is registered as an Eclipse "Server" so that the application can seamlessly integrate into the normal development workflow.

  1. Open the Servers window by going to Window -> Show View -> Servers
  2. Click on the link to create a new server (if there no existing servers) and choose the Apprenda Cloud option from the Apprenda category. Fill in your cloud's host name (NOTE: please make sure to use the full cloud URL, including the protocol https:// , e.g. https://apps.apprenda.eclipsetest) and click through to complete the wizard. Upon completion, the newly registered Apprenda cloud should be available on the list of servers.
     
  3. For a server you've already specified, you can change the Tenant by clicking List Tenants, and choosing a new tenant from the dropdown. Double click on the newly created cloud to configure it with your credentials. Fill in your username and password. If you're working with a "local/development" instance that uses a self signed certificate, be sure to check Allow Self Signed SSL Certificates. Click the List Tenants button to populate the list of tenants available for your username, and then click the Log In and Save Token button. If you click on the Applications tab, there will be no applications listed until you Add an application.

  4. Now your IDE is fully set up to run and deploy applications on Apprenda!

Create and Configure Initial Application (Dynamic Web Project)

  1. Go to File -> New , and choose Dynamic Web Project from the Web category . When you're stepping through the wizard, be sure to select Apprenda Runtime in the Target Runtime dropdown. That will configure default values for the Apprenda-specific project facets, and will add an extra page to the new project wizard that will allow you to either create a new Apprenda application or associate this project with an existing one. On the Configure Apprenda App page, either choose an existing one or create a new one.


  2. The resulting project will already have the Apprenda Features enabled because you selected the Apprenda-specific runtime as the target. Now, the project has a tiny "a" badge in the upper right corner of the project icon, the Apprenda Manifest is available in the project layout, and the Apprenda-specific actions are available in the project's context menu. If Apprenda Features are enabled, but there is no Apprenda instance, application or version alias specified, the menu items will be grayed out.

    If you already have an existing Eclipse project that was not created with Apprenda as the target runtime, enable Apprenda Features.  In the Project Explorer window, right click on the newly created project , and go to Configure -> Enable Apprenda Features. The way you will know that the Apprenda plugin features are now enabled is that now, when you click on the same project, there is a new Apprenda menu item with deployment related commands under it. Alternatively, if you go to the project properties, under the Project Facets section you can configure the Apprenda Core facet. Clicking on the Further Configuration Available... link pops up the dialog to specify the Apprenda application and version alias.


    If you chose Use Guest App API in the original setup wizard, the Java Resources > Libraries section in the project will have an Apprenda Runtime section with the guestapp-api jar listed under it.

  3. Configure the Apprenda Server defined in the previous section to use the newly created application as a Resource. Go to the Servers view/tab, right-click on the Apprenda Cloud server instance and select Add and Remove... Select the new application from the Available column on the left and click Add > to move it to the Configured column on the right. Click Finish.The server should now list your application under the server on the servers tab and the Applications tab of the server includes the app.

Deploy to Apprenda

Now that the cloud is set up and the Apprenda features are enabled, you can deploy your application to Apprenda

  1. Right click on the project and go to its properties page and pick the Apprenda category.

    • If you want to deploy your newly created application to an existing application version that already exists on Apprenda, pick the Apprenda Cloud, Application Alias, and Version Alias from the dropdowns. The dropdowns will refresh their contents as you make your choices (e.g. after you pick application eclipseapp1, the version alias dropdown will give you the versions deployed for that application).
    • If you're deploying to a new application, click the New Application button and fill in the new application properties. Upon completion of the wizard, the newly created web app and v1 version will be available in the dropdowns.
  2. Now that your application is created, start developing, e.g. add a new jsp to your project (File -> New , type JSP in the search box). Be sure to choose WebContent as the target for your JSP and name your page index.jsp so that it's the default page that gets displayed when your application runs. Add something witty to your new JSP

  3. You're ready to deploy to Apprenda! Right-click on your project, go to the Apprenda menu, and click the Deploy menu item . You should see a mini progress bar in the notification area of Eclipse and observe the deployment progress from the Progress windows ( available from Window -> Show View -> Other -> search Progress). Finally, you should be able to see the output of the deployment process in the Console"window.

  4. Your Apprenda web app is now deployed and there is a new version created in Sandbox and launching the app will give you back your witty comment back. Launch the application from the IDE or from the Browser.



     
  5. The project now shows the Apprenda Manifest that is created automatically when Apprenda Features are enabled. Although the plugin does not yet have a specialized GUI to edit the manifest, Eclipse's native XML editing capabilities based on the XSD do quite nicely.

     

Redeploy, Promote, Demote

The Eclipse plugin allows you to perform the other basic functionality when working with an Eclipse web application, but promoting and demoting the application are also available. In all cases, progress of the current operation is shown in the progress window and the output of the operation is available in the Console window.

  1. Deploy: the typical workflow after the initial creation is "code, code, code" and then hit "deploy" again. The "Deploy" action will perform the necessary steps to get a running version in Sandbox that a developer can deploy to, e.g. :

    • If the application is in Sandbox, the action will demote it, upload the new code, and promote it back to Sandbox. 
    • If the application is Published, the action will create a new version, upload the new code, and promote it to Sandbox.
  2. Promote: this is pretty straightforward, as it will promote the application (e.g. from Definition to Sandbox, or from Sandbox to Published)
  3. Demote: the opposite of promote, will demote the application from Sandbox to Definition
  4. Launch: starts up the browser and shows up the current version of the application
  5. Undeploy: demotes the application to a Definition stage
  6. Refresh: refreshes the project/application state from Apprenda Debug - debug the application of interest, and see output in the Console view

 

Auto-deploy

Eclipse allows a user to configure an application and a server in auto-deploy mode where the IDE monitors changes in the application and will automatically perform the "deploy" task

  1. Configure the Apprenda Cloud for Auto Deploy: On the Cloud properties page, be sure that the server is set to Automatically Publish changes when resources change.
  2. Configure the Application as "deployed" on the server (to enable auto-deploy)
    • Right click on the Apprenda Cloud server node, and choose Add and Remove... from the context menu.
    • Select your web app and click the Add > button to configure it for auto-deploy on the server.
    • When you click Finish to complete the wizard, Eclipse will perform an automatic deployment (you will see the results in your progress bar and console).
    • Now, just edit your JSP and save it. Eclipse will wait for a few seconds and will launch an auto-deploy process (which you can view from the progress bar and the console). After a few seconds, refresh your page; you should see that your app has been deployed.

Export Apprenda Archive

There will always be cases where a user might want to package up the application into an Apprenda archive and manually upload the changes through the Developer Portal.

Right click on the project and Choose Export from the context menu ( or go to File -> Export), type "Apprenda" in the search box and choose the Apprenda Archive option. The plugin will use the existing Eclipse WAR Export functionality to create the war file (however the user has configured it in their project) and then wraps the war into an Apprenda Archive (using the Deployment Manifest that the plugin initially generates and then maintains in the project's ".settings\com.apprenda.devtools.ApprendaManifest.xml" file).


External Resources Directory

When configuring a project for deployment to Apprenda, a directory can be specified as the source of "External Resources" that should be included alongside the WAR file in the Apprenda archive. In this way, the developer can include a variety of files and folders supported by the Platform, such as a custom context.xml file, a custom tomcat-users.xml file, or the merge folder.

With the following project setup:

The exported Apprenda archive will contain the merge folder beside the application's WAR: