Overview

A technical overview of the Codewind Eclipse IDE

Plug-ins

• Two main plug-ins:
  • org.eclipse.codewind.core
  • org.eclipse.codewind.ui
• Filewatcher plug-ins:
  • org.eclipse.codewind.filewatchers.*
• Test plug-in:
  • org.eclipse.codewind.test

Features

• The top level feature is org.eclipse.codewind.
  • The top level feature should not directly include the plug-ins, so it is built on org.eclipse.codewind.base.

Interaction with Codewind

• These classes interact with Codewind:
  • CodewindConnection: This class calls the REST APIs. This class is shrinking as more cwctl calls are used instead.
  • CodewindSocket: This class receives events from Codewind.
  • Various CLI utility classes, including CLIUtil, InstallUtil, ConnectionUtil, ProjectUtil, and more, invoke the cwctl commands.

Codewind objects

• CodewindManager is the root object that appears in the view. It also keeps track of the installation status of local Codewind.
• CodewindConnectionManager keeps track of all of the connections to Codewind instances. It also takes care of restoring connections when Eclipse starts up. Connections do not get restored until the Codewind Explorer view is opened.
• CodewindConnection represents a connection to a Codewind instance. It keeps track of the applications associated with the connection. It also makes REST API calls.
• LocalConnection represents a local connection.
• RemoteConnection represents a remote connection and handles authorization.
• CodewindApplication represents a project in Codewind.
• CodewindEclipseApplication contains Eclipse specific function, such as launching a debug session.
• RemoteEclipseApplication contains Eclipse specific function that is modified as needed for remote applications, such as setting up a port forward before launching a debug session.

Codewind Explorer view

The main component of the UI is the Codewind Explorer view.

• This view displays the connections and projects along with their current status.
• All of the actions are available from this view for the root (open the welcome page, create a new connection, etc.), the connections (create project, manage template sources, etc.), and the projects (open the monitors, build, etc.).
• See the CodewindExplorerView, CodewindNavigatorContentProvider, and CodewindNavigatorLabelProvider classes.

View actions

• All actions are added to the view dynamically using action providers.
• Each object type in the view has its own action provider, such as LocalConnectionActionProvider and CodewindApplicationActionProvider.
• In general, if an action is not supported for a particular object, it is not shown. For example, the Restart in Debug Mode action is not shown for Go projects.
• If an action is supported for a particular object, but it is not currently available, it is disabled (greyed out). For example, the Attach Debugger action is disabled if a debugger is already attached or the application is not in debug mode.
• Important: Because the actions are added dynamically, the decision to add an action or not must be fast. If not, the menu will take too long to appear. So REST APIs should not be called to add an action.

Other actions

These actions are supported outside of the view:

• A new Codewind project can be created using File>New>Codewind Project. A connection page is added to the beginning of the wizard if more than one connection is available to choose from.
• An existing project can be added by right-clicking the project and selecting Codewind>Add Project. Again, a connection page is added to the beginning of the wizard if needed.
• Concerning top level actions:
  • In the Explorer view, the user can't create a project unless there is a connection from which to access the action. Top level actions are available even when there is no connection, so by default they will install a local instance of Codewind if there are no connections. The user is prompted before this happens.
  • Also in the Explorer view, actions are disabled if the connection is not active. For top level actions, if the connection selected for the project is not started (in a local instance) or not connected (in a remote instance), it starts or connects automatically before displaying the next page of the wizard.

Welcome page

• The welcome page assists new users in getting started with Codewind for Eclipse by guiding them through the steps to get their first project running on local or remote.
• The page also has links to documentation and other useful plug-ins.
• The welcome page is displayed as the first link in the Eclipse welcome page after you install Codewind and restart Eclipse. Eclipse automatically handles the display by detecting any new extensions to the intro extension point.
• The page is also available as an action on the root Codewind element in the Explorer view.
• The page is implemented as an editor, WelcomePageEditorPart.
• The link action for the main Eclipse welcome page is GetStartedAction.

Project Overview page

• The Codewind Explorer view has limited space. The Project Overview page is provided so users can see all of the relevant information about their project.
• This page is opened automatically when a project is created or added.
• There is also an action on the project to open the overview page.
• It was decided not to provide actions in multiple places so users can't make changes to a project from the overview page, only from the Codewind Explorer view using the menus.
• Project Overview pages are closed automatically when a project is removed from Codewind.
• The overview page is implemented as an editor, ApplicationOverviewEditorPart.

Updating the UI

• When changes are received through socket events from Codewind, the UI is updated by calling the UpdateHandler and passing in the changed item, such as root, connection, or project. If the changed item is known, it is best to pass it in otherwise everything will get updated.
• The UpdateHandler manages updating the explorer view directly.
• Listeners can be added to the UpdateHandler for anything else that needs to be notified of updates (project overview pages, welcome page).
• All elements in the Codewind Explorer view have a Refresh action that users can use if anything gets out of sync.

Project Logs

• The user can display all of the logs for a project or select individual logs to display.
• All logs appear in the Console view, where the user can switch between them using the Display Selected Console toolbar menu.
• There is also a toolbar icon to enable/disable show on update for a console.
• The CodewindEclipseApplication keeps track of open consoles for the project.
• The main class is SocketConsole. SocketConsole has an update method that is called when a log update event is received on the socket.
• Consoles for a project are removed automatically if the project is removed from Codewind.

Debugging

Java

• The built-in Eclipse Java debug support is used for Java projects.
• See CodewindLaunchConfigDelegate.
• A source path computer, CodewindSourcePathComputer, maps between the Codewind project and the Eclipse project.
• For other languages, register debug launchers on the CodewindCorePlugin class, which can be turned into an extension point if needed in the future.

Node.js

• Registered as a debug launcher with CodewindCorePlugin (NodeJSDebugLauncher)
• Eclipse version 2020-03 (4.15) and later has a built-in node.js debugger. The code checks for its launch configuration type and if it is there uses the built-in debugger. There is also a preference the user can set to always use a Chrome-based browser for debugging node.js instead of the built-in debugger if desired.
• For older Eclipse versions a wizard is included which assists the user in setting up a debug session in a Chrome-based browser.
  • Allows the user to select a chrome based browser to use for debugging.
  • Provides the link to copy and paste into the browser to start the debug session.
  • Note: The tools cannot open the browser at the link as Chrome does not support this.

Remote

• For remote debugging, the debug launcher sets up a kubectl port forward before setting up the debug session.
• For Java, the port forward process is added to the debug launch.
• For Node.js, if the built-in debugger is being used the port forward is added to the debug launch, otherwise it is created as a separate launch.
• If the user disconnects the Java or built-in Node.js debug session, the port forward is automatically terminated.
• For Node.js debug sessions in a Chrome-based browser, if the user ends the debug session in the browser, they will have to go to the Debug view in Eclipse and terminate the port forward manually.

Preferences

A single preference page is available for Codewind. The page features some generic preferences:

• Timeouts for installing, uninstalling, starting, and stopping local Codewind.
• Enabling and disabling the support features.
  • When enabled, actions for support features, such as setting the PFE log level, are added to the appropriate menus in the Codewind Explorer view.
• Chrome-based browser to use for Node.js debugging.

Other UI components

• Drag and drop a project from one connection to another.
• Double-click actions on elements in the Explorer view to install or start local Codewind, connect a disconnected remote connection, or open an application in the browser. Dialogs and wizards
• Dialogs and wizards are included for managing template sources, managing image registries, and more.
• Context sensitive help provides a link to the main Codewind documentation. All dialogs and wizards should use it: PlatformUI.getWorkbench().getHelpSystem().setHelp(parent, CodewindUIPlugin.MAIN_CONTEXTID);
• Reminder: For all Eclipse dialogs and wizards, do not make any changes until the user finishes the dialog or wizard.

Development

• Use the usual Eclipse logging. Only info and error are currently available.
• Use the utility to download the latest cwctl and appsody executables:
  1. Expand the org.eclipse.codewind.core plug-in.
  2. Right-click updateBinaries.launch.
  3. Select Run As>updateBinaries.

Accessibility

• Standalone labels are not accessible. If the label is short, use a group with a title. Otherwise, use read only text. For read only text, fix the background, or it won't look good in dark mode or on a Mac. See the IDEUtil.normalizeBackground utility.
• For editors, the normalizeBackground does not work. Add a paint listener to the control. IDEUtil.paintBackgroundToMatch is the relevant utility.
• Controls inside of tables are not accessible.