docs.intersystems.com
Home  /  First Look: Atelier with InterSystems IRIS


Articles
First Look: Atelier with InterSystems IRIS
InterSystems: The power behind what matters   
Search:  


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 Database 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.
Atelier Features
Atelier provides a powerful and flexible development environment. Key advantages include:
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:
The next several sections describe how to perform some basic tasks with Atelier.
Creating a Server Connection
Development with Atelier requires a connection to an InterSystems server. 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.
  1. 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.
  2. 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:
  3. You can create a new connection by clicking the green plus sign () in the view toolbar. This actions opens the Server Connection Configuration wizard:
  4. Now, fill in the fields in the connection wizard:
    1. Connection Name: Enter a name to identify the new connection. The connection name cannot contain spaces.
    2. Next, fill in Web Server Configuration section. If you don't have the required information, you need to get it from a qualified person in you company.
      1. Address: Enter the address of the host where the server for this connection is running. The default value is localhost. This field supports IPV4 and IPV6 IP addresses in addition to server names.
      2. Web Port: Enter the WebServer port number used by the server. The default value is 57772. Note that this is not the port number for the SuperServer port.
      3. 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.
    3. Next, fill in Credentials section:
      1. Username: A valid user ID for the instance specified in the Web Server Configuration section. The user must have the required minimum privileges. See Minimum Required Privileges.
      2. Password: A valid password for the specified user.
    4. Click the Test Connection button to test the connection. You see either "Connection succeeded." or an error message.
    5. 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.
  1. 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:
  2. Next, fill in the fields in the Atelier project wizard:
    1. Enter a name for the project in the Project name field. We'll use DemoProject.
    2. Leave the check box Use default location selected, which puts your new project in your current workspace.
    3. Next, fill in the Connection Configuration section:
      1. 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.
      2. Once you have selected a server, use the Namespace drop-down list to select a namespace from those available on the server.
    4. Click Finish to create the project.
  3. 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:
  1. 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.
  2. 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:
  3. Fill in the fields in the Atelier class wizard:
    1. In the Project field, use the Browse button to select the project you just created.
    2. In the Package field, keep the default package name User.
    3. In the Name field, enter a name for the class. We’ll use MyClass.
    4. 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.
    5. The Extends field lets you specify parent classes. This field is optional, and we'll ignore it.
    6. In the Description field, enter Example class file. This field is also optional.
    7. Click Finish to create the class file.
  4. 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:
  1. 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.
  2. 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 place holder value for arguments. Then and 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:
  3. 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!"
    
    Now, the finished class method looks like this:
  4. 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:
Atelier runs the class, and you can see the output of the class method MyMethod in the Console view:
Resources for Atelier
InterSystems provides several resources for further learning about Atelier: