Thursday, August 06, 2015

New Kie Navigator for Eclipse

Eclipse Kie Navigator
The Kie Navigator is a new view created as a result of the discussion in B*MS Eclipse Tooling Enhancements. The information presented here is preliminary and reflects the current state of this view; the new feature will be delivered in its final version in Drools/jBPM Tooling 6.4.0.

The Kie Navigator View is accessed from the Eclipse Window->Show View menu:
In order to use the Kie Navigator View, the user must first define an Application Server in the WST Servers View. So, initially the Kie Navigator View will look like this:
Clicking on the link “Use the Servers View to create a new server…” will open the Servers View where a new server definition can be created. Management of the server, including startup and shutdown is done from there. Note that Drools/jBPM requires certain additional JVM and server startup options, which must be added to the server startup configuration. Once a new server has been defined, open the server configuration page (double click on the newly created server entry) and the server Overview page is opened:
Clicking the “Open launch configuration” link opens the following dialog:
Here the user can enter the app server and JVM arguments to properly configure startup of the Kie web service. See the Drools/jBPM documentation for more information about these arguments.

Alternatively, the app server and Kie web service application can be started from a command-line using either the provided Ant demo scripts or any other custom startup script. Note that starting from the Servers view may cause the app server to be shut down when exiting Eclipse. A server can also be configured in Eclipse for external management (see the “Server Behavior” section in the above screenshot.)

Once the server has been configured and started, the Kie Navigator View will recognize the server and attempt to communicate with the Kie web service. The view now looks something like this:
In this screenshot several nodes have been expanded to show all possible situations. At the root of this view is the app server. The Kie Navigator View is designed to support multiple servers, but each must obviously be configured a different hostname and/or HTTP port number. This, for example, allows management of development, test and production servers.

Below the server level are Organizational Units and Repositories. Repositories that are not currently associated with an Organizational Unit appear directly under the Server root node. Below the Organizational Unit level are the associated Repositories, and below the Repositories are Projects contained in the Repository.

A Repository can either be available () or unavailable () in the Workspace; a Repository is only available if it has been “imported” (see Context Menus, below) from the Kie web server.

Similarly, a Project can either be available () or unavailable () depending on whether it has been “imported”. When a Project has been imported, it behaves exactly the same as if it were being viewed in the Eclipse Project Explorer or Navigator; that is, all of the same menu actions available in the Project Explorer are also available in the Kie Navigator View. Also, all of the icon decorators and labels on project folders are the same as in Project Explorer.

Context Menus

This section describes the  context menu actions available for each type of node in the Kie Navigator tree.

Server

  • Refresh - causes a refresh of the entire viewer by making REST calls to the server to update the tree hierarchy.
  • Create Organization… - creates a new Organizational Unit with information collected from the following dialog:
  • Properties - displays the Server Properties dialog (see the Properties section below)

Organizational Unit

  • Add Repository… - adds a Repository that is not already associated with any other Organizational Unit to this Organization. A selection dialog containing a list of all unassociated Repositories will be displayed.
  • Create Repository… - creates a new Repository with information collected from the following dialog:
  • Delete Organization… deletes the selected Organizational Unit and dissociates any Repositories that were associated with this Organization - the Repositories are not deleted.
  • Properties - displays the Organizational Unit Properties dialog (see the Properties section below)

Repository

  • Import Repository - clones the Repository and makes it available in the Git Repository View. This menu action is only available if the Repository has not already been cloned. All actions that affect the Repository (pull, commit, push, etc.) can then be performed from the Git Repository View.
  • Create Project… - creates a new Project in this Repository with information collected from the following dialog:
If the “Import the Project” checkbox is checked, the Project will be created in the local Repository and then created, and opened  in the local workspace. If  unchecked, the Project is only created in the local Repository; it can then be “imported” at a later time. Note that the Project will become “visible” in the Kie web console immediately, but the Project contents will only be available on the server after Repository changes are committed and pushed to upstream.
  • Remove Repository… - removes the selected Repository from its containing Organizational Unit. The user will be prompted to optionally delete the Repository from the server.
  • Show in Git Repository View - opens the Git Repositories View and highlights the selected Repository in that view.
  • Properties - displays the Repository Properties dialog (see the Properties section below)

Project

This context menu is only available if the Project has not yet been “Imported” that is, it has not yet been created in the local workspace.
  • Import Project - creates a local workspace project that references the selected Project in the Repository. This makes the project available for use. If a project with the same name already exists in the workspace, the newly selected Project can not be imported.
  • Delete Project… - deletes the selected Project and removes it from its containing Repository.
  • Properties - displays the Project Properties dialog (see the Properties section below)

Once a Project has been “Imported”, it becomes synchronized with the other Eclipse resource viewers as well (e.g. Project Explorer, Java Package Explorer, Eclipse Navigator, etc.) and any changes made in any of these viewers will also be reflected in the Kie Navigator View and vice-versa. The screenshot below illustrates this effect:

Properties

Server

  • Server Name: the server name as defined in the WST Servers Viewer. This can not be changed.
  • Host Name: the name of the machine on which the app server is running. This is also managed from the WST Servers Viewer.
  • Username/Password: login credentials for the Kie web app. This is used to make REST calls to the Kie web service.
  • Trust connections to this Server: if a host is not known as a trusted site, the ssh protocol will prompt the user to verify that this is a trusted site. Setting this checkbox disables the prompt. The host can also be entered into the ssh configuration as a trusted site to avoid this problem.
  • KIE Application Name: the name of the Kie web app; the Kie Navigator will try the following application names by default to determine the app name:
    • kie-wb
    • kie-drools-wb
    • kie-jbpm-wb
    • business-central
    • drools-console
    • jbpm-console
    • jboss-brms
However, since the user has the option of renaming the Kie web app during installation, Kie Navigator may not be able to discover the actual name. This field is intended for the case where the web app name has been user-defined.
  • Use default Git Repository Path: when this checkbox is set, repositories will be cloned into the directory configured by Git (see the Eclipse User Preferences for Git.) When unchecked, the directory used in the following field will be used instead.
  • Git Repository Path: the directory to use for cloning repositories from this server; this field is only enabled if the “Use default Git Repository Path” checkbox is unset. Note that since it is possible to have many servers (e.g. production, test, etc.) with a similar organizational structure, the chances of repository name collisions are high. It is therefore suggested to use a different repository directory for each server. By default, the server name is appended to the default Git repository path, to give a unique directory name for each server.

Organizational Unit

These fields correspond to the Organizational Unit definition in the Kie web app. Note that only the Owner and Default Group ID can be changed.

Repository

These fields correspond to the Repository definition in the Kie web app. The property page also shows the remote and local Git repository locations. Note that only the description and login credentials can be changed.

Project

These fields correspond to the Project definition in the Kie web app. Currently none of these fields can be updated on the web server due to REST API limitations.

If a Project has been imported, this property page is shown in the context of the Eclipse project properties, as shown here:
 
 
Work is still ongoing, and the information here all preliminary - any suggestions for changes or improvements are welcome!


Share/Bookmark