Using the Command Line Interface and an IDE with a Java Cloud Service

Overview

    Purpose

    This tutorial covers using the Command Line Interface (CLI) and an IDE (Oracle Enterprise Pack for Eclipse) with a Java Cloud Service.

    Time to Complete

    Approximately 30 minutes.

    Introduction

    In the tutorial you will see how to use the Command Line Interface (CLI) with a Java Cloud Service. The tutorial also covers using an IDE with a Java Cloud Service. The IDE used is Oracle Enterprise Pack for Eclipse (OEPE).

    Scenario

    This tutorial assumes you are an Oracle customer. It also assumes you have completed two other Oracle by Example tutorials titled Signing Up for a Java Cloud Service and Deploying an Application to a Java Cloud Service.

    Prerequisites

    Before starting this tutorial, you should have:

    • An Oracle.com account
    • Already completed the two previous Oracle by Example tutorials titled Signing Up for a Java Cloud Service and Deploying an Application to a Java Cloud Service
    • Downloaded the Java Cloud Service SDK as part of the second tutorial.
    • An installation of WebLogic Server on your local machine, if you are going to try the part of the tutorial that uses Oracle Enterprise Pack for Eclipse (OEPE)

    Important Note about Screen Images and Terminology

    This tutorial was created with an early version of the Oracle Cloud. It is possible that some screen images here may not match exactly with what you see while working with the current version of the Oracle Cloud. It is also possible that some of the terminology may have changed. Our apologies for any confusion that this may cause you.

Using the Command Line Interface (CLI)

    To use the Command Line Interface with a Java Cloud Service, perform the following steps:

    Open a command prompt and navigate to the lib directory under the <SDK_HOME> directory. <SDK_HOME> is where you previously unzipped the Java Cloud Service SDK. In this tutorial, the SDK was unzipped to:
    C:\oracle-javacloud-sdk-1.0.0

    Run the -usage command to generate a help file on the Command Line Interface (CLI) named usage.html. This file will be placed in the current directory. The command is:
    java –jar javacloud.jar –usage

    The usage.html file contains detailed instructions on how to use the CLI.

    Open the usage.html file in a web browser and read the information on the -describeapplication and -delete commands. These are the two main commands that will be used in this tutorial.


    The CLI can be used to check the status of an application deployed to a Java Cloud Service. In a previous Oracle by Example tutorial titled Deploying an Application to a Java Cloud Service, you deployed a web application called visitors. This application's status can be checked by running the CLI with the -describeapplication command as follows:

    java -jar javacloud.jar -describeapplication –trustservercert true
    -adminurl <admin URL>
    -user <service administrator>
    -identitydomain <identity domain name>
    -serviceinstance <java service name>
    -application visitors

    Where:

    • <admin URL> is https://javaservices.cloud.oracle.com/service
      Note: This is the "Administration URL" used for all CLI and IDE interactions with the Java Cloud Service.
    • <service administrator> is the user ID of your Service Administrator. In this tutorial: bill.bell@oracle.com (use your email address instead)
    • <identity domain name> is the name of your Identity Domain. In this tutorial: obedemonstrationtrial (yours will be different).
    • <java service name> is the name of your Java Cloud Service. In this tutorial: javaservice (yours will be different).

    So, the command filled in with the valid values for this tutorial looks like this:

    java -jar javacloud.jar -describeapplication –trustservercert true
    -adminurl https://javaservices.cloud.oracle.com/service
    -user bill.bell@oracle.com
    -identitydomain obedemonstrationtrail
    -serviceinstance javaservice
    -application visitors

    When you enter the command use your Service Administrator user ID, Identity Domain name, and Java Cloud Service name.

    When the command is entered, it will prompt for the password.

    Notice the password prompt and that the password cannot be seen.

    Also notice when the application information prints out in the command prompt that the state of the application is "active."

    Next you will see how to use the CLI to undeploy the visitors application. The command to stop, undeploy, and delete an application is -delete. Any existing user sessions will be lost. Here is what the command looks like:

    java -jar javacloud.jar -delete –trustservercert true
    -adminurl <admin URL>
    -user <service administrator>
    -identitydomain <identity domain name>
    -serviceinstance <java service name>
    -application visitors

    Filling in the values for the options in this tutorial, the command becomes:

    java -jar javacloud.jar -delete –trustservercert true
    -adminurl https://javaservices.cloud.oracle.com/service
    -user bill.bell@oracle.com
    -identitydomain obedemonstrationtrial
    -serviceinstance javaservice
    -application visitors

    As before, when you enter the command use your Service Administrator user ID, Identity Domain name, and Java Cloud Service name.

    This command will also prompt you for the password.

    When you run it, the command will print out some information, including a "Job ID."

    The -delete command gives you a Job ID, because application deployment and undeployment are performed asynchronously. The Job ID can be used with the -jobstatus command to verify the status of an asynchronous job, like undeploying an application.

    Here is the -jobstatus command with the values of the options for this tutorial filled in:

    java -jar javacloud.jar -jobstatus –trustservercert true
    -adminurl https://javaservices.cloud.oracle.com/service
    -user bill.bell@oracle.com
    -identitydomain obedemonstrationtrial
    -jobid 4971

    You will be prompted for the password.

    And, of course, use correct values for your situation, including the Job ID that printed out for you.

    Notice that the job status is "complete." That means the application has been undeployed and deleted.

    The -delete command created the undeploy log file. This file can be downloaded with the -joblogfile command. The file contains the details of the undeployment process.

    Here is the command to download the undeploy log file, with the values of the options for this tutorial filled in:

    java -jar javacloud.jar -joblogfile
    -user bill.bell@oracle.com
    -identitydomain obedemonstrationtrial
    -jobid 4971 -log undeploy

    Use the values for your situation, including the correct Job ID.

    This command will also prompt you for the password.

    When the undeploy log file is examimed, you can see that the undeployment was successful.

Using an IDE with the Java Cloud Service

    The Integrated Development Environments (IDEs) that will work with the Java Cloud Service are:

    • Oracle JDeveloper
    • NetBeans
    • Oracle Enterprise Pack for Eclipse (OEPE)

    This tutorial will show how to use Oracle Enterprise Pack for Eclipse (OEPE). Documentation on using OEPE with the Oracle Cloud can be found here.

    To use OEPE with a Java Cloud Service, perform the following steps:

    First, download the correct version of OEPE version 12.1.1 using this download link:
    Download OEPE

    When you are on the download screen, select the radio button Accept License Agreement. Then download the correct "All-In-One" version of OEPE for your operating system. This tutorial uses the "Indigo" version of OEPE (Eclipse 3.7) for 32-bit Windows.

    Unzip the downloaded file to a directory of your choice, which in this tutorial will be referred to as <OEPE_HOME>.

    To start OEPE, go to the <OEPE_HOME> directory and run the eclipse executable (eclipse.exe in Windows). When the Workspace Launcher window appears, enter a workspace directory, or click the Browse button to select one.

    Then click OK.

    In this tutorial, the workspace directory is C:\workspace.

    On the Eclipse Welcome screen, which appears the first time in Eclipse, click the Workbench button.

    Once in the Workbench, from the menu select File > New > Other.

    In the New dialog window, select Oracle > Public Cloud > Oracle Public Cloud Web Project.

    Then click Next.

    On the next page of the wizard, specify a Name for the project. The Location will be filled in for you. If you already have a WAR file you want to use, check Import WAR file contents and enter the WAR file location, or click the browse button to browse the file system for the WAR file.

    Then click Next.

    Note: If you do not already have a WAR file you want to use, you may download this sample WAR file, benefits.war.

    Note for Internet Explorer Users: IE may download benefits.war as benefits.zip. It is really the same file. To get the WAR file back, just rename it to benefits.war.

    On the next page of the wizard, specify:

    • Name: This will be the name used in OEPE for the server on the Java Cloud Service. In this tutorial, the name selected is: trainingdemo (you can name the server anything you like).
    • Identity domain: This is the name of the Identity Domain of the Java Cloud Service. In this tutorial, the Identity Domain is: obedemonstrationtrial (yours will be different).
    • Service instance: This is the name of the Java Cloud Service. In this tutorial, the Service Instance name is: javaservice (yours will be different).
    • Administrator: This is the username of the Service Administrator. In this tutorial, the username is: bill.bell@oracle.com (use your Service Administrator user ID).
    • Password: The password of that user.
    • Cloud SDK: The location of the Cloud SDK. Browsing for the Cloud SDK will be shown in the next step.

    Next to the Cloud SDK field is a browse button. Click that button to browse for the location of the Cloud SDK downloaded in an earlier Oracle by Example tutorial. Select the SDK directory, and click OK.

    Once all the fields on the Cloud Target screen have valid values, you should test that the Java Cloud Service can be accessed by clicking the link Test connection.

    Also notice the Perform whitelist scan prior to publish check box. This means that before your application is "published" (the Eclipse term for deployed) to the server on the Java Cloud Service, it will be checked by the Whitelist utility to ensure that it does not use any disallowed Java packages.

    A dialog window appears to indicate whether the connection test was successful or not. If the test is successful, click OK.

    Then back on the wizard, click Next.

    Note: If the test is not successful, you need to alter some of the information entered about the Java Cloud Service and try again.

    On the next wizard screen, called Local Target, you enter information on the local installation of WebLogic Server. Because this has not been defined to Eclipse before, the Define new local target radio button is selected. Then, the Location of the WebLogic Server installation is entered.

    When all the fields have been properly filled in, click Finish.

    IMPORTANT NOTE: If you do not have a local installation of WebLogic Server, you cannot continue.

    If a dialog window appears that indicates that a new "master password" was created, follow the prompts to create password recovery information. A "master password" is used by OEPE to protect data it encrypts and stores, like the information you just entered. That master password is cached in memory. If something happens and you need to recover that password, you can answer the "recovery" questions so that OEPE can recover the master password and place it in memory once again.

    Once finished with this (or if this dialog window does not appear) go on to the next step.

    Next, OEPE asks if you want to switch to the Java EE perspective. Applications for WebLogic Server are usually built from this perspective, so click Yes.

    Now the Workbench is in the Java EE perspective. Click the Servers tab to see the servers associated with the workspace. Notice the one called trainingdemo (your name may be different). This is the server on the Java Cloud Service.

    To deploy an application to WebLogic Server from Eclipse, first you add" the project containing that application to the server. So, in the Servers tab, right-click the server for the Java Cloud Service. In the pop-up menu select Add and Remove.

    In the Add and Remove wizard, click the Add All button. This will add the Oracle Cloud Web Project, in this tutorial called oepetest (your name may be different), as the application you want to deploy to the server.

    When the Oracle Cloud Web Project (oepetest in this tutorial) is in the Configured column, click the Finish button.

    You will see a message that OEPE is "publishing" (deploying). Once the application has been uploaded and deployed, you will see the message "Synchronized" on the Java Cloud Service server. This lets you know that the latest version of the web application is deployed on that server.

    If you expand Published Modules under the server, you can see the Java Cloud Service called javaservice. Under that you can find the web application called oepetest. (Again, your names may be different.)

    To double-check that the application has really been deployed, in a web browser enter the URL for the Java Cloud Services Control console:
    https://console.cloud.oracle.com/em.

    As before, log in with the Service Administrator's credentials, and the Identity Group (Identity Domain) name.

    After logging in, you should see the Java Cloud Services Control console home page. Click the icon in the Manage column next to the Java Cloud Service. (In the tutorial the Service Instance Name is javaservice. Yours will be different.)

    On the Java Cloud Services Control screen for this Java Cloud Service you can see an entry for the oepetest application in the Applications table (your name may be different). You can tell that the deployment was successful by the green arrow in the Status column and the indication of "Active" in the State column.

    To access the deployed application, click the icon under "Test Application" in the Applications table.

    In the Application URLs pop-up window, click the URL for the application. The application will come up in another browser window or tab.

    In this tutorial, the URL for the uploaded application called oepetest is:
    https://javaservice-obedemonstrationtrial.java.cloud.oracle.com/oepetest/.

    You will now be on the starting page of the application. This is the application based on the WAR file that was imported when the project was created by checking Import WAR file contents and browsing to find a WAR file. If you chose your own WAR file, the application will look very different.

    By the way, to use this application you must log in. When you are asked, log in using your Service Administrator's credentials and Identity Group (Identity Domain) name.

    Note: If you are not asked to log in, it is because you are already logged in to the Java Cloud Services Control console and the web browser you are using uses one session ID for all open windows or tabs.

Summary

    In the tutorial you were shown how to use the Command Line Interface and Oracle Enterprise Pack for Eclipse with a Java Cloud Service.

    In this tutorial, you have learned how to:

    • Use the Command Line Interface utility to check the state of an application deployed to a Java Cloud Service
    • Use the Command Line Interface utility to undeploy an application from a Java Cloud Service
    • Create an Oracle Cloud Web Project in Oracle Enterprise Pack for Eclipse (OEPE) and deploy that web application to a Java Cloud Service by using OEPE

    Resources

    Credits

    • Lead Curriculum Developer: Bill Bell
    • Other Contributors: Reza Shafii

To help navigate this Oracle by Example, note the following:

Hiding Header Buttons:
Click the Title to hide the buttons in the header. To show the buttons again, simply click the Title again.
Topic List Button:
A list of all the topics. Click one of the topics to navigate to that section.
Expand/Collapse All Topics:
To show/hide all the detail for all the sections. By default, all topics are collapsed
Show/Hide All Images:
To show/hide all the screenshots. By default, all images are displayed.
Print:
To print the content. The content currently displayed or hidden will be printed.

To navigate to a particular section in this tutorial, select the topic from the list.