First Look: Atelier Plug-in for Eclipse
This First Look guide introduces the Atelier plug-in for Eclipse. Eclipse is a popular open-source development environment with an extensible architecture that enables support for a wide variety of languages and technologies. The Atelier plug-in extends that support to the InterSystems IRIS® data platform, bringing InterSystems IRIS into the Eclipse 'ecosystem'. When you develop applications with Atelier, you edit and save source files on your client machine. You compile, run, and debug source files on a server instance, using a connection you create and maintain in Atelier.
To browse all of the First Looks, including others that can be performed on a free Community Edition instance as described below, see InterSystems First Looks.
Atelier provides a powerful and flexible development environment. Key advantages include:
Eclipse is a widely-known open-source development environment.
The Eclipse Consortium and other parties provide extensive learning resources.
The Atelier plug-in enables you to develop applications in Eclipse using InterSystems technology. The extensive array of plug-ins and extensions available for Eclipse means you can use whatever additional technologies your project requires, all in a single development environment.
Atelier is able to draw on the powerful debugging capability built into Eclipse.
Eclipse plug-ins exist for virtually all widely-used version control systems (VCS), which enables you to use the VCS of your choice to manage development.
Trying Atelier for Yourself
In order to try Atelier, you must first download and install Eclipse. Then you can install the Atelier plug-in. The Atelier Download page describes the steps necessary to get up and running with Atelier.
The first time you start Eclipse, it asks you to select a workspace. An Eclipse workspace is just a directory on your local disk where Eclipse stores the resources you use for development. Once you are running the Eclipse application, you have a number of resources available to guide you through your first steps:
Cheat Sheets that provide step-by-step guidance through basic Atelier tasks. Select Help > Cheat Sheets... from the main menu, open the Atelier folder, and select a topic of interest. You may want to work through the cheat sheets in the order listed, as each one builds on previously covered material.
Product Documentation, which is available by selecting Help > Help Contents from the main menu.
The Getting Started section provides an introduction to Atelier and the Eclipse UI.
The Concepts section introduces the major components and capabilities of Atelier.
The Tasks section contains topics that walk you through a number of useful tasks with Atelier.
The Reference section provides more detailed technical information about Atelier.
The next several sections describe how to perform some basic tasks with Atelier. You may find it helpful to view the brief video Setting Up Atelier with InterSystems Products before getting started.
Selecting and Connecting to an InterSystems IRIS Instance
Development with Atelier requires a a running InterSystems IRIS instance to connect to. Your choices for InterSystems IRIS include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. In connect Atelier to your InterSystems IRIS instance, use the connection information in InterSystems IRIS Connection Information in the same document.
Creating a Server Connection
One of the first tasks you must perform when getting started with Atelier is to define one or more server connections. The following steps describe how to create a connection.
Your first step is to open the Atelier perspective. An Eclipse perspective is a set of UI resources, or views, that help you perform a group of related tasks. In this case, we need the Server Explorer view, which is part of the Atelier perspective.
To open the Atelier perspective, click on the Open Perspective button, shown in the following screen shot:This button opens a dialog, shown in the next screen shot, that lists available perspectives.Select Atelier and click Open.
Once you're in the Atelier perspective, click on the tab for the Server Explorer view. The next screen shot shows the Server Explorer view selected, with one existing connection:
You can create a new connection by clicking the green plus sign () in the view toolbar. This action opens the Server Connection Configuration wizard:
Now, fill in the fields in the connection wizard with the connection information for your instance from in Connecting an IDE.
Connection Name: Enter a name to identify the new connection. The connection name cannot contain spaces.
Next, fill in Web Server Configuration section.
Address: Enter the DNS name or the IPV4 or IPV6 address of the host on which the instance for this connection is running.
Web Port: Enter the webserver port number used by the server.Note:
Do not enter the superserver port number at this prompt.
Secure Connection: Leave this box unchecked. In a real-world application, you would want to use a secure connection, but that's not necessary for this quick introduction.
Next, fill in Credentials section:
Username: A valid user ID for the instance specified in the Web Server Configuration section. The user must have the minimum required privileges. See Minimum Required Privileges.
Password: A valid password for the specified user.
Click the Test Connection button to test the connection. You see either "Connection succeeded." or an error message.
Once the connection test had completed successfully, click the Finish button to create the connection.
The newly created connection is listed in the Server Explorer. You can open the connection node and drill down to examine the resources provided by the connection.
Creating a Project
Atelier uses projects to organize your work, so your next step is to create a project.
Right-click in the Atelier Explorer view to open the context menu and select New > Atelier Project, as illustrated in the following screen shot:This action opens the New Atelier Project wizard:
Next, fill in the fields in the Atelier project wizard:
Enter a name for the project in the Project name field. We'll use DemoProject.
Leave the check box Use default location selected, which puts your new project in your current workspace.
Next, fill in the Connection Configuration section:
Server: Use this drop-down list to select the server you configured in the previous section. If you need to create a new server connection at this point, the button labeled Configure server... opens the Server Connection Configuration wizard for you.
Once you have selected a server, use the Namespace drop-down list to select a namespace from those available on the server.
Click Finish to create the project.
You can now see your new project listed in the Atelier Explorer, as shown in the following screen shot:.
Creating a Class File
Files that contain Atelier classes end with a .cls extension, and are referred to as class files. Follow these steps to create an Atelier class file:
Right-click in the Atelier Explorer view to open the context menu and select New > Class File, as illustrated in the following screen shot:This action opens the New Class File wizard.
The first page of the wizard lets you select a file template. Select the Empty Class template and click Next. The next page lets you configure the class:
Fill in the fields in the Atelier class wizard:
In the Project field, use the Browse button to select the project you just created.
In the Package field, keep the default package name User.
In the Name field, enter a name for the class. We’ll use MyClass.
The Filename field contains the name of the class file as it appears in the local file system. The default value is the class name you just entered, with the extension .cls.
The Extends field lets you specify parent classes. This field is optional, and we'll ignore it.
In the Description field, enter Example class file. This field is also optional.
Click Finish to create the class file.
At this point, your new class is listed in the Atelier Explorer and open in the editor, as shown in the following screen shot:.
Note that there is a warning badge on the name of the new class in the Atelier Explorer and in the editor, pointed out by the red arrows in this screen shot:If you hover the cursor over the small yellow rectangle in the upper-right margin of the editor area, you see the warning: Resource is out of sync in namespace. This problem results from the file having been created and saved on the client, but not yet synchronized to the server. This issue will be resolved when you edit and save the file in a later step.
Adding a Class Method
You can now add a class method to the class:
You can use the Eclipse content assist feature to help you add a class method. In the editor, position the cursor in the body of the class and type c followed by CTRL+Space. A content-assist pop-up appears that suggests possible completions given cursor position and what you've already typed. The following screen shot shows the pop-up:
Select the classmethod template and type Enter. The class editor adds the class method template, as shown in the next screen shot.
Next, fill in the template. First replace the documentation placeholder with An example class method, then use tab to advance to the next field. Replace name with MyMethod. In the next field, remove the placeholder value for arguments. Then set type to %Status. Again, content assist can help you. Type %St followed by CTRL+Space. Select %Status and type Enter. Now, the class method looks like this:
In this step, you fill in the rest of the content for this sample class. Above the return statement, add the following lines:
set retVal = $$$OK write "Hello world!"Copy code to clipboard
Now, the finished class method looks like this:
Right-click and select Save. This action saves the file to the local file system, synchronizes the file with the server, and compiles it.
Running the Class
Now you can use Atelier to run the class you have just created. Right-click in the Atelier Editor view and select Run As > Atelier Application, as shown in the following screen shot:
Learn More About Atelier
InterSystems provides the following resources to help you learn more about Atelier: