The Cloud Foundry Blog

Cloud Foundry Integration for Eclipse Can Now Launch External Command-line Applications Using Service Tunnels

In the course of developing, testing and deploying cloud applications, developers sometimes need to directly access the application data. The Cloud Foundry Integration for Eclipse advances this capability and now features the ability to launch external command-line applications for Cloud Foundry services like MySQL and PostgreSQL. The plugin offers Spring and Java developers using Eclipse or STS a way to manipulate, or port the data contained in their Cloud Foundry applications more easily.

An earlier release of the Cloud Foundry plugin (1.1.0) introduced tunneling support for data services, and the command-line application feature in 1.4.0 now extends the support by automatically resolving tunnel values when launching a command-line application for a Cloud Foundry service. In addition, a set of predefined commands for executing commonly used command-line applications are available by default, and ready to use if the external command-line application is installed and set in the operating system’s PATH environment variable.

These commands are launched from within Eclipse or STS, and executed in an external command-line terminal. New commands can be defined either through a new Eclipse preference page for Cloud Foundry, or by opening a Service Tunnel Commands wizard from the Services table in the Cloud Foundry Server editor. The commands are stored as Eclipse preferences and therefore persisted across Eclipse runtime sessions.

In this blog, we will describe the steps to define and launch a new mysqldump command that automatically generates a dump file for a Cloud Foundry MySQL service. This blog assumes the reader has basic understanding of how to create a Cloud Foundry server in Eclipse, as well as create services through the Cloud Foundry Server editor’s Applications tab.

The command-line application feature in 1.4.0 allows users to launch an external application by simply selecting a service in the Services table in the Cloud Foundry Server editor and right-clicking to execute a particular command from the Services table context menu (see Figure below). The launch process then automatically creates a tunnel if one was not already created and executes the command in the operating system’s default terminal application. Terminal applications can also be changed per command definition. For example, in Linux the default terminal used by the feature is xterm, yet a user can change a command to use a different terminal like gnome-terminal.

Predefined Commands

The Cloud Foundry Integration for Eclipse version 1.4.0 provides a list of predefined commands that are ready to use for MySQL, PostgreSQL, MongoDB, and Redis services, provided the corresponding applications are installed. The commands are accessible by right-clicking on a service in the Services table in the Cloud Foundry Server editor:

cf140_base_context_menus

The list of commands are:

MySQL:

  1. mysql
  2. mysqldump

MongoDB:

  1. mongo
  2. mongodump
  3. mongorestore

PostgreSQL:

  1. psql

Redis:

  1. redis-cli

If these applications are already set in the operating system’s PATH environment variable, these commands can be executed right away without changes, and are launched in an external terminal like Terminal.app for Mac OS X, cmd.exe for Windows, and xterm for Linux.

For example, launching mysql for a MySQL service in the Cloud Foundry editor will automatically connect the mysql application to the MySQL service in the Cloud Foundry server through a tunnel, provided mysql is installed and set in the OS PATH environment variable. The end result is an external terminal window opening outside of Eclipse, displaying the mysql application prompt:

cf140_external_terminal_mysql

Since the tunnel credentials are resolved automatically for the external application by the Cloud Foundry plugin, the mysql application automatically connects to the data service and opens the mysql prompt without asking the user for credentials.

If new commands need to be added, or existing ones edited, they can be done so by either selecting Command Definitions in the Services table context menu, or by opening Eclipse Preferences -> Cloud Foundry -> Service Tunnel External Application Commands

Creating a New mysqldump Command

In our example, we will be adding a new mysqldump command that creates a particular output dump file called myoutputfile.txt. Although a mysqldump command already exists by default as part of the set of predefined commands, we will create a separate one where a dump file is explicitly set.

Commands are associated per service vendor, so the new mysqldump command will apply to any MySQL service regardless of the Cloud Foundry server.

To add a new command, choose Command Definitions from the Services table context menu to open the Service Tunnel Commands wizard, select the desired service, and click “Add”.

cf140_service_tunnel_commands_wizard

This will open the Command Definition wizard:

cf140_pt1_add_command

Two required properties are needed to define a command:

  1. A unique display name. Two or more commands with the same name cannot exist for a given service.
  2. An executable location, or just the name of the application if already set in the OS PATH environment variable.

Optionally, a user can also define command options that are passed to the application when it is being executed, and environment variables that are set by the Cloud Foundry plugin prior to launching the command. Option variables using the pattern ${variablename} can be used in the options definition.

These variables are grouped into two types:

  1. Tunnel-specific variables that are reserved for tunnel values like username, password, port, and database name. These variables are automatically resolved by the Cloud Foundry plugin when the command is launched.
  2. Additional variables that will be prompted to the user in a dialogue when the command is executed.

Some applications like psql require that passwords be set as environment variables. As with command options, variables using the pattern ${variablename} can be used in place of environment variable values.

cf140_add_env_variables

In addition, the terminal definition can also be adjusted for that particular command, and optionally applied to all current and future commands by editing the terminal launch command value in the External Command Line Terminal section.

To facilitate creating custom commands, the list of predefined commands are available via a drop-down control, and can be used as templates for new definitions:

cf140_pt1b_predefined_mysql

Let’s select mysqldump from the list. It will now populate the wizard with the default definition for myslqdump, including the necessary options required to run the application. Since we already have a default mysqldump command, an error will appear asking the user to set a different display name:

cf140_pt2_name_already_exists

Now, we want to edit the display name and give it a unique name, and also set a specific name for the dump file: myoutputfile.txt. In addition, we are changing the location of the mysql executable as we do not have it set in the OS PATH environment variable.

cf140_pt3_edited_command_definition

Clicking “Finish” in the Command Definition wizard will now add the command to the list of commands for the MySQL service:

cf140_pt4_commands_wizard_with_changed_name

Clicking “Finish” once more in the Service Tunnel Commands wizard will persist the changes. At this point, clicking “Cancel” will alternately cancel any changes made to any services.

Now let’s right-click on the MySQL service in the Services table, and we’ll see the newly added mysqldump with outputfile command in the context menu. Selecting this command will execute it, and if necessary, automatically create a tunnel connection if one wasn’t already present.

cf140_pt5_context_menu_new_command

After the command executes, the following dump file is created in the user’s home directory:

cf140_pt6_mysql_dump

If instead of executing the custom mysqldump with outputfile that was created above, a user runs the default mysqldump command where the dump file is defined using an ${output file} variable, a dialogue will open prompting the user for the name of the output file prior to executing the command. The file name can include an absolute path, or if just specifying a name, it will be created relative to the user’s home directory.

cf140_pt7_prompt_outputfile

Variations in Terminal Launch

The command-line feature for 1.4.0 is supported in Mac OS X, Linux and Windows. However, there are differences in how a command is launched in an external terminal. For Mac OS X, the default terminal is Terminal.app, and the Cloud Foundry plugin executes the command and sets any environment variables in a temporary .sh script file that it creates and then passes as an argument to Terminal.app. This temporary file is deleted after the process running the command is launched.

For Windows and Linux, no temporary script file is created, and instead the command and its options are passed directly to the external process as process arguments.

Installing Cloud Foundry Integration for Eclipse 1.4.0

To install version 1.4.0, follow the documented instructions to install Cloud Foundry Integration for Eclipse. Earlier versions of the integration, starting from 1.0.0 can be updated from within Eclipse or STS. Note that updates for older Cloud Foundry plugins prior to 1.0.0 are not supported, and must first be uninstalled before installing 1.4.0.

Only Eclipse JEE Indigo and Juno, as well as STS 2.9.0 and GGTS 3.0.0 and higher are supported.

This entry was posted in Announcement, CloudFoundry, Media. Bookmark the permalink.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title="" rel=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>