Eclipse Scout: Frontend

Scout is an open source framework for building business applications. The Scout framework covers most recurring aspects of a classical client server architecture with a strong focus on the application’s front-end. With its multi-device capability, a Scout client applications may run simultaneously as a rich client, in the browser and on mobile and tablet devices.

To different groups of people, Scout means different things. End users are interested in a good usability, the management cares about the benefits a new framework can offers to the organisation and developers want to know if a framework is simple to use and helps them to solve practical issues. This is why the text below describes Scout from the perspective of these three roles.

Most large organizations develop and maintain enterprise applications that have a direct impact on the success of the ongoing business. And at the same time, those responsible for the development and maintenance of these applications struggle with this task. It is a big challenge to adapt to changing business demands and complying with the latest legal requirements in time. And the increasing pressure to lower recurring maintenance costs does not make the situation any easier.

It often seems that too many resources are required to keep a heterogeneous set of legacy technologies alive. In this situation, modernizing mission critical applications can help to improve over the current situation. For the target platform stack, Java is a natural choice as it is mature, widely adopted by in the industries and unlikely to become legacy in the foreseeable future. While for the back-end side of enterprise applications well-known and proven frameworks do exist, the situation on the client side is less clear. Unfortunately, user interface (UI) technologies often have lifetimes that are substantially shorter than the lifetimes of larger mission critical applications. This is particularly true for the web, where many of today’s frameworks will no longer be relevant in five or more years.

Enter Eclipse Scout. This open source framework covers most of the recurring needs that are relevant to the front-end development of business applications. And Scout forces a clean separation between the user interface and the specific UI technology used for rendering. This has two major benefits. First, Scout developers implement the user interface against an abstraction layer, which helps to focus on the business functionality and saves development time. And second, long term maintenance costs are lower, as the Scout code remains valid even when the rendering technology needs to be exchanged. Therefore, Scout helps to improve the productivity of the development teams and reduces the risk of major application rewrites.

To provide a first impression on the scope and goals of the Scout framework, a number of scenarios where Scout typically contributes to your projects success are listed below .

That Scout should help in the last two situations mentioned above seems to be contradictory at first but is just based on a simple principle. Where possible, the Scout framework provides abstractions for areas/topics.[4] that need to be implemented for business applications again and again. And for each of these abstractions Scout provides a default implementation out of the box. Typically, the default implementation of such an abstraction integrates a framework or technology that is commonly used.

When needing a working prototype application by the end of the week, the developer just needs to care about the desired functionality. The necessary default implementations are then automatically included by the Scout tooling into the Scout project setup. The provided Scout SDK tooling also helps to get started quickly with Scout. It also allows to efficiently implement application components such as user interface components, server services or connections to databases.

In the case of applications with long lifespans, the abstractions provided by Scout help the developer to stay productive and concentrate on the actual business functionality. At the same time, this keeps the code base as independent of specific technologies and frameworks as possible. This is a big advantage when individual technologies incorporated in the application reach their end of life. As all the implemented business functionality is written against abstractions only, no big rewrite of the application is necessary. Instead, it is sufficient to exchange the implementation for the legacy technology with a new one. And often, an implementation for a new technology/framework is already provided by a more recent version of Scout.

The text below provides guidelines on what to read (or what to skip) depending on your existing background. We first address the needs of junior Java developers that like to learn more about developing enterprise applications. Then, we suggest a list of sections relevant for software wizards that already have a solid understanding of the Eclipse platform, Java enterprise technologies, and real world applications. Finally, the information needs of IT managers are considered.

Before you can start with the “Hello World” example you need to have a complete and working Scout installation. For this, see the step-by-step installation guide provided in Appendix Scout Installation. Once you have everything installed, you are ready to create your first Scout project.

Start your Eclipse IDE and select an empty directory for your workspace. This workspace directory will then hold all the project code for the “Hello World” application. Once the Eclipse IDE is running it will show the Scout perspective with the Scout Explorer view and an empty Scout Object Properties view. To create a new Scout project select the New Scout Project…​ context menu as shown in Figure 6.

In the New Scout Project wizard enter a name for your Scout project. As we are creating a “Hello World” application, use org.eclipsescout.helloworld for the Project Name field according to Figure 7. Then, click the Finish button to let the Scout SDK create the initial project code for you.

Once the initial project code is built, the Scout SDK displays the application model in the Scout Explorer as shown in Figure 8. This model is visually presented as a tree structure covering both the client and the server part of the application. The Scout Explorer view on the left hand side displays the top level elements of the complete Scout application. Under the orange node the Scout client components are listed. Components that are needed in both the Scout client and the Scout server are collected under the green node. And the Scout server components are listed below the blue node in the Scout Explorer view.

After the initial project creation step we are ready to start the server and the clients of the still empty Scout application. For this, we switch to the Scout Explorer and select the root node org.eclipse.scout.helloworld. Selecting the application’s org.eclipse.scout.helloworld node in the Scout Explorer displays the product launchers in the Scout Object Properties. As we can see in Figure 9, we have product launchers for four different development products.

Each product launcher box provides a link to the corresponding Eclipse product file.[17], the configuration file.[18], as well as three launcher icons to start and stop the corresponding application. The green Circle icon starts the product in normal mode. The Bug icon just below, starts a product in debug mode. To terminate a running product, the red Square icon is provided. Alternatively, you can also stop products by clicking on the same red icon in the console view. This is shown on the right hand side of Figure 9. Client products may also be stopped by closing the client’s main window or using the provided File ▸ Exit menu.

Before any of the client products is started, we need to start the server product using the green circle or the bug launcher icon. During startup of the Scout server you should see console output similar to the one shown on the right hand side of Figure 9. Once the server is running, you may start the web client as shown in Figure 9, the Swing client, or the SWT client in the same way. And with a running RAP product, the Scout web client can be opened in a web browser. Just click on the provided Automatic Device Dispatch link or open a a browser and manually type the address http://localhost:8082/web into the browser’s navigation bar.

Having started the Scout server and all client products, the client applications should become visible as shown in Figure 10.

The project creation step has created a Scout client that displays an empty desktop form. We will now add widgets to the client’s desktop form that will later display the “Hello World!” message.

To add any widgets to the desktop form, navigate to the DesktopForm in the Scout Explorer. For this, click on the orange client node in the Scout Explorer view. Then, expand the Forms folder by clicking on the small triangle icon, and further expand the DesktopForm. As a result, the MainBox element becomes visible below the desktop form as shown in Figure 11. With a click of the right mouse button over the MainBox, the available context menus are displayed. To start the form field wizard select the New Form Field …​ menu.

In the first step of the form field wizard shown on in Figure 12 choose GroupBox as the form field type and click on the Next button. In the second wizard step, enter ‘Desktop’ into the Class Name field before you close the wizard with the Finish button. The Scout SDK will then add the necessary Java code for the DesktopBox in the background.

We can now add the text field widget to the group box just created. To do this, expand the MainBox in the Scout Explorer view to access the newly created DesktopBox element. On the DesktopBox use the New Form Field …​ menu again. In the first wizard step, select StringField as the form field type according to Figure 13. To select the StringField type you can either scroll down the list of available types or enter “st” into the field above the field type list. In the second wizard step, enter ‘Message’ into the Label field. As we do not yet have the text ‘Message’ available in our “Hello World” application the wizard prompts the user with the proposal New Translated Text …​.

With a double click on this option a new text entry can be added to the application as shown in Figure 14. Once an initial translation for the message label is provided, close the translation dialog with the Ok button. Finally, close the form field wizard using the Finish button.

By expanding the DesktopBox element in the Scout Explorer, the new message field becomes visible. Now, double click on the message field element to load the corresponding Java code into an editor and displays the message field’s properties in the Scout Object Properties as shown in Figure 15. This is a good moment to compare your status with this screenshot. Make sure that both the Java code and the project structure in the Scout Explorer look as shown in Figure 15.

Having verified your status of the “Hello World” application start the start the server and a client of the application as described in the previous section. The client applications will then display your message widget. However, the text widget is still empty, as we did not yet load any initial content into this field. This is the topic of the next section.

The responsibility of the Scout server in our “Hello World” application is to provide an initial text content for the message field in the client’s user interface. We implement this behaviour in the load method of the server’s DesktopService. An empty stub for the load method of the DesktopService service has already been created during the initial project creation step.

To navigate to the implementation of the desktop service in the Scout SDK, we first expand the blue top-level server node in the Scout Explorer. Below the server node, we then expand the Services folder which shows the DesktopService element. Expanding this DesktopService node, the load method becomes visible as shown in Figure 16.

The DesktopService represents the server service corresponding to the DesktopForm on the client side. This initial setup represents Scout’s default where client forms and server services typically come in pairs. Whenever the client’s user interface displays a form to the user, the client connects to the server and calls the load method of the corresponding server service. We just need to add our business logic to the load method of the server’s DesktopService.

According to the signature of the load method, a formData object is passed into this method that is then handed back in the return statement. To complete the implementation of the load method it is sufficient to assign the text 'hello world!' to the message field part of the form data. The complete implementation of the load method is provided in Listing 1.

With this last element we have completed the Scout “Hello World” application.

For Eclipse Scout applications a slick look and feel called Rayo is available in the Eclipse Marketplace.[19]. And in this (optional) part of the “Hello World” tutorial we will add Rayo to our “Hello World” Swing client application. As a result, we will get a Scout desktop application that looks the same as the corresponding Scout web client as shown in Figure 17.

To add Rayo in the Scout SDK to our “Hello World” project, switch to the Scout Explorer and select the top-level org.eclipse.scout.helloworld node. Then, according to Figure 18, select the checkbox Rayo Swing Look and Feel for Eclipse Scout under the Technologies section of the Scout Object Properties. This brings up a dialog showing the proposed changes to application’s target file and the Swing plugin of the “Hello World” application. These changes need to be confirmed with the OK button. The first time the user adds the Rayo feature in the Scout SDK, Eclipse needs to download the package from the Eclipse Marketplace. This download and subsequent installation of Rayo will make you to go through the following steps.

After the successful download and installation of the Rayo package, start the Swing client using the procedure described in Section Run the Initial Application. When we also start the web client of the “Hello World” application using the RAP product launcher, we can compare the result side by side.

We are now ready to move the finished “Hello World” application from our development environment to a productive setup. The simplest option to move our application into the ‘wild’ is to use the Export Scout Project wizard provided by the Scout SDK. Using the default settings, the export wizard produces two WAR files.[20] that contain the complete Scout server and the desktop and mobile client applications.

To deploy the application to a web server the WAR files generated by the wizard are the only artefacts needed. The first WAR file contains the Scout server including a zipped desktop client for downloading. In the second WAR file, the RAP server application that provides both the web client and the client for mobile devices.

To start the export wizard, we start the Scout SDK with the “Hello World” Scout project. In the Scout Explorer we then select the corresponding Export Scout Project…​ context menu on the “Hello World” top level application node as shown in Figure 19. In the first wizard dialog shown in Figure 20, the target directory for the WAR files needs to be specified. You may choose any directory as the target directory.[21]. After clicking Next button the second wizard step proposes the server product file that specifies the artefacts to be exported including the file name for the WAR file for the “Hello World” server application. Typically, the proposed default values are fine. Move to the third dialog with Next button.

In the third dialog of the Export Scout Project wizard the desktop client to be included in the WAR file needs to be specified. The default selection is set to the SWT client application. For the “Hello World” example, we want to include the Swing client application with the Rayo Look and Feel. For this, we need to change the selected product to helloworld-swing-client.product (production) according to Figure 21. With Next button we move to the last wizard step.

In the last wizard dialog shown in Figure 22, the RAP server product and the corresponding WAR file name are specified. Normally, the proposed field values are fine and we can close the wizard with Finish button. After this last step, the Scout SDK is assembling the necessary artefacts and building the two “Hello World” WAR files. These two WAR files are the only items needed for deploying the “Hello World” application to a web server

As the final step of this tutorial, we deploy the two WAR files representing our “Hello World” application to a Tomcat web server. For this, we first need a working Tomcat installation. If you do not yet have such an installation you may want to read and follow the instructions provided in Appendix Apache Tomcat Installation. To verify a running Tomcat instance, type http://localhost:8080/ into the address bar of the web browser of your choice. You should then see the page shown in Figure 23.

Once the web browser displays the successful running of your Tomcat instance, switch to its “Manager App” by clicking on the button highlighted in Figure 23. After entering user name and password the browser will display the “Tomcat Web Application Manager” as shown in Figure 24. If you don’t know the correct username or password you may look it up in the file tomcat-users.xml as described in Appendix Directories and Files.

After logging successfully into Tomcat’s manager application, you can select the WAR file(s) to be deployed using button “Choose File” according to the right hand side of Figure 24. After picking your helloworld_server.war and helloworld.war file and closing the file chooser, click on button “Deploy” (located below button “Choose File”) to deploy the application to the Tomcat web server. This will copy the selected WAR file into Tomcats webapps directory and unpack its content into a subdirectory with the same name. Deploying the file helloworld.war will extract its contents into a subdirectory named helloworld. And the file helloworld_server.war will be extracted into subdirectory helloworld_server. You can now connect to the deployed application using the browser of your choice and enter the following address.

You will then see the home page of the server of your “Hello World” application shown in Figure 25. From here you can download the zipped client application that can be saved in a directory of your choice. After unpacking the zip file, you may start the executable file named helloworld. This will start the “Hello World” client application as shown on the left hand side of Figure 26. To start the “Hello World” web application, open a browser and enter the following address.

Depending on the device your browser is running on you will be redirected to helloworld/web on a desktop or laptop computer, to helloworld/mobile on a mobile device or to helloworld/mobile if you are connecting from a tablet device. Figure 26 shows screenshots for a desktop client, the web application and the same application in a mobile browser. As demonstrated in these screenshots helloworld/web and helloworld/mobile lead to a different presentation of the same UI optimized to the target form factors of desktop browsers, tablets, and mobile phones.

The first thing you need for the creation of a new Scout project is to select a new workspace. For Eclipse, a workspace is a directory where Eclipse can store a set of projects in a single place. As Scout projects typically consist of several Eclipse plugin projects the default (and recommended) setting is to use a single workspace for a single Scout project.

In the case of the “Hello World” application, the workspace contains seven plugin projects as shown on the left side of Figure 27. In the expanded source folder of the client plugin org.eclipse.scout.helloworld.client the organisation of the Java packages is revealed. The Scout Explorer provided on the right side of Figure 27 shows three colored top level nodes below the main project org.eclipse.scout.helloworld.

In the Scout Explorer, the main project node expands to the orange client node org.eclipse.scout.helloworld.client, the green shared node org.eclipse.scout.helloworld.client and the blue server node org.eclipse.scout.helloworld.server. The client node first presents the white user interface (UI) nodes org.eclipse.scout.helloworld.client.ui.* indicating the supported UI technologies. Next, the client mobile node org.eclipse.scout.helloworld.client.mobile is shown. It is responsible for adapting the layout of the user interface suitably for mobile and tablet devices. Finally, after the ClientSession node and the Desktop node, component specific folders allow for a simple navigation to the various client parts.

Comparing the Package Explorer with the Scout Explorer a couple of aspects are notable. First, the number and names of the Eclipse plugin projects is identical in both the Package Explorer and the Scout Explorer view. However, the Scout Explorer recognizes the Scout project structure and explicitly renders the relation between the different Eclipse plugins. In addition, individual node colors are used to indicate the role of each plugin project. Second, the focus of the Scout Explorer lies on the business functionality of the complete client server application. Artefacts only necessary to the underlying Eclipse platform are not even accessible. Third, on the individual elements rendered in the Scout Explorer, the Scout SDK provides menus to start wizards useful to the selected context. In the case of the “Hello World” tutorial we could create the complete application (except for a single line of Java code) using these wizards .

When we revisit the New Scout Project wizard in Figure 7, it now becomes trivial to explain how the Project Name field org.eclipse.scout.helloworld was used as the common prefix for plugin project names and Java package names. Based on the project name, the last part helloworld was used for the Project Alias field. As we have seen in Section Exporting the Application, this project alias is used by the Scout SDK to build the base names of the WAR files in the export step. In turn, after deploying the WAR files as described in Section Deploying to Tomcat, the RAP server application becomes available under the URL http://localhost:8080/helloworld. Should you have a catchy naming for you application in mind, com.mycompany.mycatchyname is therefore a good choice for the Project Name field.

In this section, we will walk you through the central Scout application model components of the “Hello World” example. As each of these components is represented by a Java class in the Scout framework, we can explain the basic concept using the available “Hello World” source code. Below, we will introduce the following Scout components.

Please note that most of the Java code was initially generated by Scout SDK. In many cases this code can be used “as is” and does not need to be changed. Depending on your requirements, it might very well be that you want to adapt the provided code to fit your specific needs. However, a basic understanding of the most important Scout components should help you to better understand the structure and working of Scout applications.

Using the UI of the “Hello World” application we explain in this section how the Scout UI form model is represented in Java. We also describe how this representation is exploited by the Scout SDK to automatically manage the form data objects used for data transfer between Scout client and Scout server applications. Finally, will have a brief look at internationalization.[33] support of Scout for texts.

As discussed in Section Form Scout forms consist of variables, the main box and a number of form handlers. The main box represents the visible part of Scout’s form model. It may holds any number of form fields. Using container fields such as group boxes, it is possible to define complex structures such as hierarchical UI models containing multiple levels. In the Scout framework the forms structure is represented in the form of inner classes that are located inside of the MainBox class. And the New Form Field wizard of the Scout SDK fully supports this pattern. Listing 4 provides the concrete example using the the desktop form of the “Hello World” tutorial.

Using inner Java classes to model a form’s content is a central aspect of the UI part of the Scout application model. It allows the Scout SDK to easily parse the form’s Java code on the fly and directly reflect changes to the form model in the Scout Explorer and the Scout Property View. However, this is not the only benefit for the Scout SDK. As form data objects hold all form variables and the values of all form fields contained in the form, the Scout SDK can keep the form data classes in sync with the forms of the application. It is important to note that this mechanism only depends on the Java code of the form field class. In consequence, the Scout SDK can update form field classes in the background even when form fields are manually coded into the form’s Java class. This includes adding all the necessary getter and setter methods to access the values of all the fields defined on a form. As a result, Scout developers don’t need to manually update form data objects when the UI model of a form is changed. The Scout SDK takes care of this time consuming and error prone task.

When we did add the Message field to the desktop form of the “Hello World” application we had to enter a new translation entry for the label of the message field as shown in Figure 13. The individual translation entries are then stored in language specific text property files. To modify translated texts we can use the NLS editor.[34] provided by the Scout SDK as shown in Figure 33.

To access the translated label field entry in the application, the Scout SDK generated the implementation of getConfiguredLabel using TEXTS.get("Message") as shown in Listing 4. In the default Scout project setup, calling TEXTS.get uses the DefaultTextProviderService in the background. This text provider service then defines the access path for the text property files to use for the translation. To resolve the provided key, the user’s locale settings are used to access the correct text property file.

In this background section we take a closer look at Scout services and calling service methods remotely. We will first discuss the setup of an ordinary Scout service. Then, the additional components to call service methods remotely are considered. To explain the concepts in a concrete context, we use the setup of the DesktopService of our “Hello World” example.

Rayo has been designed in 2009 by BSI for its CRM.[37] application and contact center solution. Since then, Rayo has been copied for Scout web applications and also adapted to work on touch/mobile devices.

The implementation of Rayo for desktop clients is based on the Java Synth look and feel.[38]. However, in a few cases it was necessary to adjust some of the synth classes. In order to do this, the adapted classes are copied form the OpenJDK implementation.[39] As OpenJDK is licenced under the GNU General Public Licence (GPL) with a linking exception it is not possible to distribute Rayo under the Eclipse Public Licence. That is why Rayo is not initially contained in the Eclipse Scout package but needs to be downloaded from the Eclipse Marketplace. Fortunately, there is still no restriction to use Rayo in commercial products. The only remaining restriction applies to modifying Rayo for commercial products. In this case you will be obliged to redistribute your modified version of Rayo under the same licence (GPL with classpath exception).

With Eclipse Scout 3.8 (Juno), the Scout framework also allows to build web clients based on Eclipse RAP. Great care has been taken to ensure, that the look and feel for Scout web applications matches the look and feel of the desktop as closely as possible. As RAP is already distributed under the EPL licence the Rayo for web apps is directly contained in the Scout package. TODO: Describe what to change to use RAP default look and feel

A similar approach was chosen for Rayo on tablets and mobile devices that are supported with Eclipse Scout 3.9 (Kepler). For such devices optimized components are used to take into account the smaller screens and the absence of a mouse (no context menus!) But as far as possible, the Rayo look and feel also applies to touch devices. TODO: Pointer to more info regarding mobile devices.

In this background section we look at the content and organisation of the two WAR files generated by the Scout SDK Export Scout Project wizard. The first WAR file holds the Scout server including a landing page to download the Scout desktop client. The desktop client is provided in the form of a standalone ZIP file. In the second WAR file, the Ajax server based on Eclipse RAP is contained. This Ajax server provides the URLs that can be accessed by web browsers running on desktop computers or tablet and mobile devices.

The content and its organisation of the exported WAR files was not specifically designed for Scout applications. Rather, it is defined according to server-side Equinox.[40], the typical setup for running Eclipse based server applications on a web server. Using file helloworld_server.war as a concrete example, we will first describe the general organisation of the WAR file. Then, we introduce individual artefacts of interest that are contained in this WAR file.

The explicit organisation of the server WAR file is shown in Figure 35. From the left hand side of the figure we can see that on the top level only folder WEB-INF exists in the WAR file. This folder contains all files and directories that are private to the web application. Inside, the web deployment descriptor file web.xml as well as the directories lib and eclipse are located. While the web.xml file and directory lib are standard for servlet based based applications.[41], directory eclipse contains all necessary artefacts for servlet based Eclipse applications.[42]. Such as Eclipse Scout server applications.

On the right hand side of Figure 35 the eclipse specific content of the WAR file is shown. From top to bottom we find the configuration file config.ini introduced in Section Eclipse Configuration Files. In folder plugins the necessary plugins that constitute the eclipse application are located where the plugins are available in the form of JAR files.[43]. This includes plugins for servlet management, the eclipse platform including the servlet bridge, the scout framework parts and of course our “Hello World” server and shared plugin. These “Hello World” jar files exactly match with the plugin projects discussed in Section Create a new Project.

In Figure 36 some of the content of the “Hello World” server plugin is shown. The first thing to note is that the plugin file conforms to the JAR file format including a META-INF/MANIFEST.MF file and the directory tree containing the Java class files, as the DesktopService.class implemented in Section The Server Part of the “Hello World” tutorial. In folder resources/html the necessary files for the download page shown in Figure 25 including the zipped desktop client are contained. To access this download page the Scout server’s resource servlet ResourceServlet is responsible. It is registered under the servlet registry as shown in Listing 9. With setting "/" of the alias parameter the download page becomes available under the root path of the Scout server application. For the mapping to the contents resources/html the parameter bundle-path is used.

Revisiting the “Hello World” server plugin project in the Eclipse package explorer as shown in Figure 37, we can see how the plugin project elements are transformed and copied into the JAR file. Examples files are plugin.xml and MANIFEST.MF as well as static HTML content of the download page (files index.html and scout.gif). The zipped client is missing of course. It is assembled, zipped and added into the Scout server JAR file by the Export Scout Project wizard of the Scout SDK. In case you need to change/brand/amend the download page for the desktop client, you have now learned where to add and change the corresponding HTML files.

In this section we will discuss two common pitfalls when working with the Scout IDE and Tomcat. The symptoms linked to these problems are Scout server applications that are not starting or Scout applications that fail to properly update.

In usual culprit behind Scout server applications that fail to start is a blocked port 8080. This setting can be created when we try to run both the Jetty web server inside the Scout SDK and the local Tomcat instance. In consequence, either Jetty or Tomcat is not able to bind to port 8080 at startup which makes it impossible for a client to connect to the right server. To avoid such conflicts, make sure that you always stop the Scout server application in the Scout SDK (effectively killing Jetty) before you restart your Tomcat server. Alternatively, you can assign two different ports to your Jetty webserver and your Tomcat webserver.

To modify Jetty’s port number in the Scout SDK you have to update the corresponding properties in the config.ini files of the development products of your Scout server application and all client applications. In the Scout server’s config.ini file the property is named org.eclipse.equinox.http.jetty.http.port, in the client config.ini files the relevant property is called server.url. To change the port number to 8081 for the “Hello World” example in the Scout SDK you could use the following lines in the individual config.ini files.

The second pitfall is connected to a web application that seems to refuse to update to the content of a freshly generated WAR file. At times it seems that your changes to a deployed WAR file do not find their way to the application actually running. In many cases this is caused by a cached instance of the previous version of your application located in Tomcat’s working directory. To save yourself much frustration, it often helps just to clear Tomcat’s working directory and restart Tomcat. For this, you may follow the following procedure.

How you start and stop Tomcat depends on the platform you are running it. If you have installed Tomcat on a Windows box according to Appendix Apache Tomcat Installation it will be running as a service. This means that to stop the Tomcat web server you need to stop the corresponding Windows service. For starting and stopping Tomcat on Mac/Linux/Unix systems, you can use the command line script files startup.sh and shutdown.sh located in Tomcat’s subdirectory bin.

For those interested in more advanced aspects of Apache Tomcat we recommend the article “More about the Cat” by Chua Hock-Chuan.[44].

needs text

Existing Documentation

needs text

Existing Documentation

Code types and codes are widely used in business applications. In general, any fixed set of named entities can be seen as a code type. Code types can be used to model the organisational structure of companies, to represent business units or to categorise or segment entities. Frequently, enumerations or enumerated types.[45] are used as synonyms for code types. The individual named entities in a code type are called codes in Scout.

Both code types and codes have associated names (translated texts) and IDs. As in the case of standard Java enumerations, Scout codes can also have associated values. A set of additional features enhances Scout code types over simple Java enumerations:

The text below first introduces the basic features of code types and codes using a simple example with static codes. Then, hierarchical code types and the dynamic loading of codes from external sources is explained.

Lookup calls are are used to look up lists of lookup rows in the form of key-text pairs. The list of lookup rows returned is usually defined by some search criteria. When the look up is triggered by a key, only a single element is returned. And when a string is provided as a search criteria, the returned list typically contains the lookup rows that contain the given search text as a substring.

For lookup calls two main use cases exist. In the first case, the lookup data is locally available, not too large and can be kept in memory. In this situation, the lookup data can be directly created in the call itself. As an example, you may consider a lookup call where the lookup data is based on a code type. In the other case, the lookup data is dynamic in nature, the amount of data is large and needs to be read from some external source, such as a database or a web service. To access large amounts of external data, a lookup call typically invokes a so called lookup service that is providing the necessary data. This is exactly the scenario that was used in the “My Contacts” application of the book’s first part in Section [sec-adding_the_smartfield]. In the contact form of that application, a company smart field is used to let the user select a specific entry from a list of companies. And in turn, this smart field uses a company lookup call that is backed by a company lookup service. This lookup service then accesses a database to create the list of companies required for the company smart field.

in the text below

TODO: fix Figure 39: MyLookupService extends AbstractLookupService and implements IMyLookupService that extends ILookupService which

needs text, topic is relevant for client, server, and security. what to present where to be decided

needs text, explain that form data objects are data transfer objects

Existing Documentation

needs text

needs text

needs text

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

needs text

Existing Documentation

needs text

Every Scout form contains one or several form fields. Form fields therefor represent the basic building blocks of a forms content. Depending on their nature, form fields can display information, accept user input or act as container holding inner form fields. As such container fields can hold inner container fields it is possible to create forms that meet compolex requirements.

Existing Documentation

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

Needs text

Existing Documentation

The application is organized into separate outlines for thematic groups of widgets. Each of the application’s outline then presents a list of widgets in a navigation tree. This is shown in Figure 41 for the Simple Widgets outline that contains examples for simple UI widgets such as label fields or string fields.

For each UI widget a corresponding example form presents a number of typical use cases and configuration options. The example forms are designed to be independent from each other. It should therefore be possible to read and understand the source code of each example form with minimal effort. Via the Open in Dialog …​ context menu the content of the view is displayed in a modal scout form. As shown in Figure 41, the complete source code for the selected form can be accessd via the View Source on GitHub context menu.

The widget demo application can also be run as a native SWT desktop application. This is shown in Figure 42. And the exact same application also runs in a browser as a web application shown in Figure 43.

In Figure 44, the content of the widget demo application is shown on a mobile device. On the home screen of the mobile application, the available outlines are presented. When the user selects a specific outline, the associated navigation tree is then shown as a scrollable list. Finally, when the user selects a specific widget, the associated example form is shown.

As the sole purpose of the widget demo application is to demonstrate the usage of the UI elements provided by the Scout framework, no server side data access and/or business logic is required. Therefore, the widget demo application has been designed as a client only application. As a side effect, the architecture of this widget application may also be used as a template to build similar client only applications with the Scout framework. It is important to note that this architecture can only be recommended for very simple applications. For more complex software packages, for example personal digital archives or private accounting software, it is not recommended to implement the business logic and the access to the database in the application’s client plugin. A much cleaner approach is to take advantage of the offline support provided by the Scout framework. As in typical Scout client server projects, the presentation logic can be implemented in the client plugin and business logic and access to a (local) database are located in the server plugin. A detailed description of this setup including step-by-step instructions is available on the Scout Wiki.[47]. In the text below the client only setup of the widget demo application is explained by looking at the main differences to the setup of the “Hello World” application introduced in Chapter “Hello World” Tutorial.

The most obvious difference of the widget demo application to the “Hello World” client server example is the missing server (plugin). Consequently, the widget demo application also does not need a service tunnel to handle client server communication. As the setup of this service tunnel is typically initiated in method execLoadSession of the client’s ClientSession class, the setup of the service tunnel has been commented out in the widget demo application according to Listing Listing 16.

The next difference between typical Scout applications and the widget demo lies in the handling of code types and codes. Accessing code types and codes is the responsibility of the server’s CodeService class in Scout applications. As the widget demo does not have a server but we still want to work with codes and code types, a LocalCodeService class has been added to the client’s plugin.

The last difference of note between the “Hello World” example and the widget demo application lies in the implementation of the form handler classes. In the desktop form’s view handler of the “Hello World” application the data to be displayed is retrieved via the server’s DesktopService as shown in Listing Listing 3. As the forms of the widget demo application do not load/persist any data from/to a server, no such logic is required in the form handlers and the corresponding classes remain empty.

Label fields are used to place a read only text anywhere in a Scout form. As shown in the configuration section of Figure 000 such texts can occupy the typical area assigned to a label field on the left, the area typically assigned to data entry on the right or on both sides. The form shown in Figure 000 is implemented in class LabelFieldForm of the Scout widget application.

To set the label text in the default area method getConfiguredLabel is used. If the label text is too long for the reserved area the label gets truncated with trailing …​. The complete label text is then shown in a tooltip.

As for any form field derived from AbstractFormField, a number of getConfigured* styling properties exist for label fields. Most of these styling properties can directly be set in the Scout Object Properties view. A subset of these properties are shown in the list below.

To display text in the right hand area an empty string can be used as label text and the text for the value area of the label field can be set with method setValue in method execInitField according to Listing [lst-field.label.value].

To display multiline text across both the label and the value area a combination of label field properties has to be used. See Listing Listing 18 for the configuration used in the last label field shown in Figure 000.

String fields are used to enter simple text strings. In addition, string fields are also useful to enter multiline text or capture masked input. The form shown in Figure 000 is implemented in class StringFieldForm of the Scout widget application.

Some of the most typical use cases for string fields are represented in the examples section of Figure 000. In the configuration section of the form a multiline text field is shown. As in the case of the label text, font and color styling possibilities are available for the text shown in a string field. Clicking on the Sample Format button and on the Sample Content button prefills some of the fields to create the effect shown in Figure 000.

In the case of multi line string fields, the field can be configured to either display text lines as they have been entered or wrapped to fit into the available width of the field. This property can be set with the string field’s method getConfiguredWrapText or dynamically with method setWrapText. Please note that changing this property dynamically at runtime currently only works with the SWT and the Swing rendering components.

(AbstractStringField,String Field

Additional use cases for the string field are shown in the right column of the configuration section of the string field demo form. Specific string fields are located for the default case, a string field only accepting upper case letters, and a masked field. To code to represent the masked string field is provided in Listing Listing 19. Independent of what the user is typing the masked field keeps the entered content visually hidden. In contrast to all other forms of string fields, the content cannot be copied to the system clipboard. It can only be accessed programmatically with the getValue method of the string field.

String fields also allow for the configuration of the maximum length of the text that can be entered into the field. In its default configuration, a maximum number of 4'000 characters can be entered into a string field. Using method setMaxLength this limit can be updated dynamically at runtime. Alternatively, this limit can also be set in method getConfiguredMaxLength.

For entering numbers, Scout provides three different fields. Depending on the valid range of numbers that may be entered, an integer field, a long field or a big integer field best matches the given use case. These fields are represented by the classes AbstractIntegerField, AbstractLongField and AbstractBigIntegerField, each one of them extinding class AbstractNumberField.

The form NumberFieldsForm of the Scout widget application shown in Figure 000 contains examples for all three number field types. Separate buttons are available to demonstrate the use of the minimum and the maximum value a number field can hold. In the case of the BigInteger field, arbitrarily large or small values may be entered. See Listing Listing 20 for the code corresponding to the input integer field in the configuration section of the example form.

(AbstractIntegerField,Integer Field

As already indicated by the class names of the three number fields, the fields serve to enter values that fit into the ranges defined by the Java classes Integer, Long and BigInteger. To further restrict the bounds of valid numbers you may use the methods getConfiguredMinValue and getConfiguredMaxValue. The effect of setting such bounds can be tested by entering values into the Minimum Value field and the Maximum Value field of the example form. If, for example, a minimum value of 0 is entered in the Minimum Value field and the user tries to enter the value -1 into one of the input fields, an error marker becomes visible on the input field. A tooltip with the text `"The value is too small; must be between 0 …​`" further explains the issue to the user. In such a case the value entered into the user interface is not propagated to the number field’s value. This is why the read only getValue() field is not updated in such a case.

To textually format the entered numbers the grouping number field property can be used. In the example form the Grouping checkbox can be used to control this property. Ticking/unticking this checkbox will affect the three number input fields in the configuration section of the example form.

More extensive options to specify the formatting of the numbers is provided by the method setFormat of class AbstractNumberField. Method setFormat is accepting an argument of the Java class DecimalFormat. To demonstrate an example for such a format click on Sample Format button in the example form. For more information please consult the Javadoc for class DecimalFormat.

Scout provides two different form fields for entering decimal values. Depending on the required precision and range of values to be entered a double field or a big decimal field can be used. The two field types are represented by Scout’s classes AbstractDoubleField and AbstractBigDecimalField and can hold values of the Java types Double and BigDecimal respectively. Both the double and the big decimal field extend class AbstractDecimalField which in turn extends class AbstractNumberField.

The example form shown in Figure 000 demonstrates the usage and some of the available options to configure Scout’s decimal fields. This example form is defined in class DecimalFieldsForm of the Scout widget application.

(AbstractDoubleField,Double Field

The styled double field in the example section of the form displays negative values in red and postive values in the default black color. This behaviour is implemented in method execChangedValue according to Listing Listing 21. The sample value shown initially is provided in the execInitField method. Setting the red foreground color explicitely is needed in method execInitField as the execChangedValue is only triggered after the initial form is displayed on the screen.

For displaying and storing the fraction digits of decimal values three different properties exist. Two of them, the getConfiguredMinFractionDigits and the getConfiguredMinFractionDigits affect the optical representation of the decimal value. To configure the amount of fraction digits that is effectively represented the property getConfiguredFractionDigits is used. The need for three different properties might not be immediately clear. To illustrate the concept, let us look at an example use case where a decimal field always has to display exactely 3 fraction digits. Should the user provide more fraction digits we would like to capture this additional information up to 5 fraction digits.

To configure this behaviour the following settings for this decimal field may be used.

If the user enters the text “3.141592653589793” into this field and tabs to the next field, the field will then display the text “4.142” but actually hold the value 3.14159. And if the user just enters a “3”, the field will display “3.000” and hold the value 3.0.

Decimal fields can also be configured to enter percentages in a convenient way. For this use case the Multiplier property can be set to 100 and the Multiplier property to true. If the user now enters “5” into such a decimal field, it will show the text “5%” and hold the value 0.05.

As in the case of number fields more extensive options to specify the formatting of the numbers is provided by setFormat method of the decimal field. Method setFormat is accepting an argument of the Java class DecimalFormat. To demonstrate an example for such a format click on Sample Format button in the example form. For more information please consult the Javadoc for class DecimalFormat.

To work with date and time values Scout offers three dinstinct form fields. The AbstractDateField allows the user to enter a date and the AbstractTimeField is used to enter a time. The third field AbstractDateTimeField combines date and time entry into a single form field. Both classes AbstractTimeField and AbstractDateTimeField are extending the AbstractDateField field.

The form DateTimeFieldsForm of the Scout widget application shown in Figure 45 contains examples for the date and time fields of Scout. Separate buttons are available to provide samle values and to demonstrate the formatting options for displaying date and time values. Displaying dates and times is highly depending on the used locale. That is why the currently used locale is shown in the example section of the form.

To enter date and time values the user can either click on the date and time icons/buttons provided by the fields or directly enter text into the fields. For entering dates the key arrows provide a number of shortcuts. Entering the currnt date can be done by pressing the Up. Once a day is entered in a date or a combined day time field, the Up and the Down can be used to step to the next/previous day. Simultaneously pressing the Shift or the Ctrl allows to step to the next/previous month or year.

The code of the DateTimeDisabledField field shown in Listing Listing 22 represents the disabled combined date time in the example form. Before the form is opened Scout executes its execInitField method and sets the fields value to the current date and time.

In the configuration section the local can be used at runtime to test the effect of the locale to displaying date and time fields. As changing the locale at runtime only works reliably in rich clients the field is only editable in the Swing or the SWT client. To specify the exact formatting of the displayed date and time values a specific format can be set in the getConfiguredFormat method of the date and time fields. Internally, Scout is using the provided string to create a Java SimpleDateFormat for formatting. Valid examples for the formatting are entered into the format fields of the example dialog by pressing the Sample Formats button. The string “EEEE” shown in date field format field represents the day of the week as shown in configuration section of Figure 45. As expected, the textual representation of the day of the week is depending on the used locale.

Check boxes can be used to enter/represent simple boolean values. In Scout, check boxes are derived from class AbstractCheckBox.

In the Scout widget application the use of check boxes is demonstrated in the form CheckboxFieldForm that is shown in Figure 46. To access the current value, Scout provides the method isChecked for check box fields. This naming reflects the boolean state of a check boxes and differs from the other Scout value fields that provide a getValue method.

A coding example is provided in Listing Listing 23 for the disabled check box. The initial value is set in method execInitField using the method setChecked.

With radio buttons the user can select a single element out of a number of distinct choices. For this, a number of radio buttons may be placed into a radio button group field where a radio button group extends class AbstractRadioButtonGroup. The contained individual buttons are extending class AbstractRadioButton.

Figure 000 demonstrates the use of radio button groups in Scout. It is implemented in class RadioButtonGroupFieldForm of the Scout widget application. As shown in the example section of the form, radio buttons may have labes and/or icons assigned.

The simplest way to define the content of a radio button group is by using its configuration properties getConfiguredCodeType or getConfiguredLookupCall. Listing Listing 24 provides the implementation of “Default” radio button group DefaultGroup. This radio button group is typed by the generic parameter Long and the individual radio buttons are obtained from the code type EventTypeCodeType specified in method getConfiguredCodeType. Please note that the Long type matches the key type of the codes in the EventTypeCodeType. The generic parameter used in the definition of a radio button group also determines the type that will be returned by the group’s getValue method.

Alternatively, the individual buttons in a radio button group can also be defined as inner classes. This approach has been used for the “Styled” radio button group in the example section of the RadioButtonGroupFieldForm. The corresponding code is provided in Listing Listing 25. The type of the value that is returned by the getValue method is defined on the radio button group. In the provided listing, the StyledGroupBox is configured to return a value of the type Long. Consequently, the individual radio buttons are returning radio values of the type Long as well in the getConfiguredRadioValue methods. The field PlaceholderField in the radio button group only serves layouting purposes. Without this place holder field, the two radio buttons of the styled radio button group would be evenly distributed in the available space.

Buttons and links are used to trigger actions in Scout. Buttons come in two variations, normal push buttons and toggle buttons. While buttons have an associated label and/or icon, links can only have a label. Buttons extend class AbstractButton and links extend AbstractLinkButton.

Example uses of buttons and links are shown in the form ButtonLinkFieldsForm of the Scout widget application shown in Figure 000.

In it’s simplest form a button just extends class AbstractButton and overrides getConfiguredLabel to set the label. The example in Listing Listing 26 also has an icon assigned and stretches over the whole column width. In addition, the example button overrides method getConfiguredProcessButton to return false. This has the effect that buttons (and links) appear at the exact location where they are defined in a field container. Otherwise, buttons (and links) are placed at the bottom of the container they are defined in.

The code of the default toggle button in the example form of the widget application is provided in Listing Listing 27. To query the state of a toggle button method isSelected can be used.

In the configuration section of the example form the use of mnemonics using the character & is demonstrated. Please note, that this feature is not identically available across the different supported UI technologies. In the Swing UI shown in Figure 000 the label “&Toggle” has the effect, that pressing the ALT+T key combination changes the toggle state of this button. In the case of the SWT UI the alt key is not necessary. Pressing the T changes the toggle state. In contrast to the Swing UI the letter ‘T’ is not underlined. To optically indicate shortcut letters in the SWT UI it is recommended to adapt the label from “&Toggle” to “[&T]oggle”. The RAP UI does not currently support mnemonics on buttons.

Message boxes are used to provide information to a user or ask the user simple yes/no questions. In Scout, class MessageBox provides a number of static convenience methods for this purpose. Additionally, message boxes are shown to the user in the case of a processing exception or a veto exception.[48].

In the examples section of the MessageBoxForm form shown in Figure 000 a number of links is provided. Clicking on any of these links opens a corresponding message box via the static convenience methods available with class MessageBox. For example, calling MessageBox.showOkMessage(title, header, info) opens a message box with a title, a header text and some additional information.

In addition to the static convenience methods, message boxes can be configured to meet specific requirements by a number of parameters. These parameters are shown in Figure 000 in the configuration section of the sample form MessageBoxForm of the Scout widget application. Clicking on the Sample Content button will fill in example values for the message box parameters. The configured message box can them be started by clicking on the Open the configured MessageBox link. This behaviour is implemented in the link’s execClickAction method according to Listing Listing 28. The text below details the purpose of less evident message box properties.

Message box buttons only appear if an non-emtpy label text is assigned to the Yes Button Text property, the No Button Text property and Cancel Button Text property. If the hidden text property has a non-empty text assigned, an additional Copy button will be added to the message box. An example use case is the case of elaborate error messages (or complete stack traces in cases where this does not negatively impact the application’s security). Here the copy button allows to transport this text into the system clipboard. From the clipboard the user may decides to paste this text into an email to the companys help desk. The default return value property specifies the return value of the message box if the box closes autmatically after the time provided in the auto close millisecond property has passed. If the auto close millisecond property is set to -1, the message box will not clause automatically.

Once a message box is started with method startMessageBox the user interface is blocked until the user chooses any of the options or clicks the dialog away. The selected option is the provided by the method’s return value. If the user closes the message box by hitting the esc or clicking on the icon to close a dialog, the start method of the message box will always return the value CANCEL_OPTION of the IMessageBox interface.

List boxes allow a user to select a subset of a predefined list of elements. The individual elements are displayed in the form of checkable options. To check or uncheck a specific element, the user may click on a element or press the Space when an element has the focus. To define the list of elements that are presented in a list box, code types or a lookup calls can be used. Example use cases using both code types and lookup calls for the definition of the presented elements are implemented in class ListBoxForm of the Scout widget application. See Figure 47 for a screenshot of the example form.

In the example section of Figure 47 the list boxes in the left column retrieve the elements to be displayed from code types. And in the right column, the displayed elements are retrieved from lookup calls. The implementation of the top left Default field is provided in Listing Listing 29. List boxes are derived from class AbstractListBox and parameterized by the type of keys of the elements. Please note that the specified key type of a list box must match the key type of the elements provided by code types or lookup calls. In our example, the list box type Color matches the key type of the code type ColorsCodeType configured in method getConfiguredCodeType.

In the List Content field located on the right hand side of the configuration section of Figure 47 it is also possible to enter user defined content. After entering some example data and pressing the Tab, the user content is parsed and used to update the elements displayed in the ListBox field. To get the initial example data shown in Figure 47, use the Sample Content button of the list box example form. Basically, the content of each text row is parsed into a lookup row according to the format provided in the first row of the sample content: # key;text;iconId;…​. The resulting lookup rows are then used to dynamically update the content of the lookup call associated with the ListBox field. List boxes can be configured to only display the checked elements. For this, the configuration method getConfiguredFilterCheckedNodes may be used.

To access the currently selected elements of a list box method getCheckedKeys may be used. This is demonstrated in Listing Listing 30 using the getCheckedKeys field in the example form. In order to get notified for every change of the list box field, the list box field is registered as the master in method getConfiguredMasterField. The implementation of method execChangedMasterValue is then called whenever the state of the master field is changed. In the case of Listing Listing 30, the list of selected keys can be retrieved from the list box and shown in the getCheckedKeys field.

To read or write the content of a list box field from or to a form data on the server side, methods getValue and[java]setValue have to be used. Both methods work with typed sets, requiring the type defined for the list box field.

Tree box fields allow a user to select a subset of a predefined list of elements. The difference to list boxes lies in the organisation of the presented elements. Instead of presenting the elements as a list, a tree structure is used with tree box fields.

To check and uncheck a specific element, the user may click on a element or press the Space when an element has the focus. In addition, tree boxes can also be configured to check or uncheck the complete sub tree when clicking on an element. To define the trees presented in tree boxes, hierarchical code types and lookup calls can be used. Example use cases for tree box fields are implemented in class TreeBoxForm of the Scout widget application. A screenshot of the tree box example form is shown in Figure 48.

In the example section of Figure 48 the tree boxes in the left column retrieve the elements to be displayed from hierarchical code types. And in the right column, the displayed elements are retrieved from hierarchical lookup calls. The implementation of the top right Default field is provided in Listing Listing 31. Tree boxes are derived from class AbstractTreeBox and parameterized by the type of keys of the tree elements. As in the case of list box fields, the the specified type of a tree box must match the key type of the code type or the lookup call. In our example, the tree box type String matches the type of the lookup call YearsMonthsLookupCall configured in method getConfiguredLookupCall.

In the configuration section of the form shown in Figure 48 the user may enter any tree data into the Tree Content field. To get the initial tree data shown in Figure 48, use the Sample Content button. Tree boxes can be configured in several ways. Using method getConfiguredAutoExpandAll, the element tree will be initially expanded. Configuration method getConfiguredFilterCheckedNodes hides all elements that are not checked. And with method getConfiguredAutoCheckChildNodes, checking or unchecking a tree element automatically updates the elements in the subtree accordingly.

To access the currently selected elements, the tree box method getCheckedKeys returns a typed set of keys. The type of the key set is determined by the type of the tree box. To read or write the content of a tree box field on the server side, methods getValue and[java]setValue have to be used. Both methods work with typed sets, requiring the type defined for the tree box field.

Smart fields are used to select a single value from a set of named elements. As smart fields offer “search-as-you-type” functionality, the field works well for very large sets of elements. The content of smart fields can either be provided by code types or lookup calls. Consequently, smart fields work with both lists and hierarchical structures and the content may come from a static set of values or is dynamically provided at runtime.

To select an elements in a smart field the user can either use the mouse or the keyboard. Pressing the Up Arrow or the Down Arrow in the field shows the list of entries when the smart field has the focus. Alternatively, the use can click with the mouse on the smart field icon. By typing a part of the name of the desired entry into the field, the “search-as-you-type” support kicks in and a filtered list of elements is displayed. The selected entry can be confirmed by using the Enter or the Tab.

Example use cases for smart fields are provided in class SmartFieldForm of the Scout widget application and a screenshot of this example form is shown in Figure 49. The left hand side of the demo form contains smart fields based on list content and on the right hand side smart fields backed with hierarchical content are shown. In the example section of the demo form, some smart fields are backed by code types and others by lookup calls. And in the configuration section the content shown in the smart fields can be entered manually at runtime. To obtain the content shown in Figure 49, use the Sample Content button.

Existing Documentation

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

needs text

needs text

Existing Documentation

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

needs text

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

Existing Documentation

needs text

needs text

Existing Documentation

needs text

This work is licensed under the Creative Commons Attribution License. To view a copy of this license, visit https://creativecommons.org/licenses/by/3.0/ or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.

A summary of the license is given below, followed by the full legal text.

You are free:

Under the following conditions:

Attribution ---You must attribute the work in the manner specified by the author or licensor (but not in any way that suggests that they endorse you or your use of the work).

With the understanding that:

Waiver ---Any of the above conditions can be waived if you get permission from the copyright holder.

Public Domain ---Where the work or any of its elements is in the public domain under applicable law, that status is in no way affected by the license.

Other Rights ---In no way are any of the following rights affected by the license:

Notice ---For any reuse or distribution, you must make clear to others the license terms of this work. The best way to do this is with a link to https://creativecommons.org/licenses/by/3.0/.

Copyright (c) 2012-2014.

In the text below, all contributing individuals are listed in alphabetical order by name. For contributions in the form of GitHub pull requests, the name should match the one provided in the corresponding public profile.

Bresson Jeremie, Fihlon Marcus, Nick Matthias, Schroeder Alex, Zimmermann Matthias

The full licence text is available online at http://creativecommons.org/licenses/by/3.0/legalcode

This chapter walks you through the installation of Eclipse Scout. The installation description (as well as the rest of this book) is written and tested for Eclipse Scout 4.0 which is delivered as integral part of the Eclipse Luna release train, 2014. Detailed information regarding the scheduling of this release train is provided in the Eclipse wiki.[49].

We assume that you have not installed any software relevant for the content of this book. This is why the Scout installation chapter starts with the installation of the Java Development Kit (JDK). Consequently, you will have to skip some of the sections depending on your existing setup.

In the text below, installation routines are described separately for Windows, Mac, and Linux. As Scout applications have been built primarily on the Windows platform in the past, Scout also has the highest maturity level on this platform.

The first step to install Scout is to have an existing and working installation of a JDK version 7 or 8. It is currently recommended to go for the most recent download of Java 7.

Using Scout with Java 8 is possible and has been tested as part of Eclipse release train testing.[50]. We are currently not aware of any productive installation so far, but this is likely to change in the near future as Oracle’s published end of public updates for Java 7 is scheduled for April 2015.[51].

You may still use Scout with Java 6. However, this version is no longer tested with Scout and has reached Oracle’s end of public updates on February 2013. Older Java versions will no longer work together with the Scout framework.

Currently, we recommend to install the Oracle JDK 7 together with Scout. Although, using OpenJDK with Scout should work too. To successfully install the JDK you need to have at least local admin rights. You also need to know your hardware architecture in order to download the correct JDK installer.

For Windows, the steps necessary to determine your hardware architecture are described on Microsoft’s support site.[52]. For Linux several ways to determine if your os is running with 32 or with 64 bits can be found on the web.[53] For Mac this step is simple, as only a 64 bit package is provided on JDK the download page.

Once you know your hardware architecture, go to Oracle’s official download site.[54] and accept the licence agreement by clicking on the appropriate radio button. Then, select the Windows x64 package if you are running 64-bit Windows as shown in Figure 60. If you are running 32-bit Windows, go for the Windows x86 package. It is also recommended to download the Java SE 7 Documentation. The Java API documentation package is available from the official download site.[55], located further down under section Additional Resources.

Once you have successfully downloaded the JDK installer, follow the Windows installation guide.[56]. To verify the installation you might want to go through this Java “Hello World!” tutorial.[57].

Installation instructions for Linux.[58] and Mac.[59] are also available from Oracle.

Before you can install Scout make sure that you have a working Java Development Kit (JDK) installation of version 7 or 8. To download the Eclipse Scout package visit the official Eclipse download page as shown in Figure 61.

If the download page shows the wrong platform, manually select the correct platform in the dropdown list. As shown in Figure 61, the Scout package is available as a 32 bit and a 46 bit package. Make sure to pick the package that matches your JDK installation. You can check your installation on the command line as follows.

If the output explicitly mentions the 64 bit installation as shown above, you have a 64 bit installation. Otherwise, you have a 32 bit JDK installed. Now you can select the correct Scout package from the Eclipse download site. After the package selection, confirm the suggested download mirror as shown in Figure 62.

As the Scout package is a simple ZIP (or tar.gz) file, you may unpack its content to a folder of your choice. Inside the eclipse sub-folder, you will then find the Eclipse executable file, such as the eclipse.exe file on a Windows plattform. Starting the Eclipse executable brings up the workspace launcher as shown in Figure 63.

Into the Workspace field you enter an empty target directory for your first Scout project. After clicking the Ok button, the Eclipse IDE creates any directories that do not yet exist and opens the specified workspace. When opening a new workspace for the first time, Eclipse then displays the welcome screen shown in Figure 64.

To close the welcome page and open the Scout perspective in the Eclipse IDE click on the Workbench icon. As a result the empty Scout perspective is displayed according to Figure 65.

Congratulations, you just have successfully completed the Eclipse Scout installation!

If you have only installed a single JDK you will not need to change the default eclipse.ini file of your Eclipse installation. In case you have installed multiple JDKs coming with their individual Java Runtime Environments (JREs), you might want to explicitly specifiy which JRE to use. Open the file eclipse.ini in a editor of your choice and insert the following two lines at the top of the file:

where the second line specifies the exact path to the JRE to be used to start your Eclipse Scout installation.

If you have explicitly specified the JRE to be used you verify this in the running Eclipse installation. Fist, select the Help ▸ About Eclipse menu to open the about dialog. Then, click on the Installation Details button and switch to the Configuration tab. In the long list of system properties you will find lines similar to the ones shown below.

You have now successfully completed the Eclipse Scout installation on your Windows environment. With this running Scout installation you may skip the following section on how to add Scout to an existing Eclipse installation.

This section describes the installation of Scout into an existing Eclipse installation. As the audience of this section is assumed to be familiar with Eclipse, we do not describe how you got your Eclipse installation in the first place. For the provided screenshots we start from the popular package Eclipse IDE for Java EE Developers.

To add Scout to your existing Eclipse installation, you need to start Eclipse. Then select the Help ▸ Install New Software…​ menu as shown in Figure 66 to open the install dialog.

In the install dialog, click on the Add…​ button to enter the link to the Scout repository. This opens the popup dialog Add Repository As shown in Figure 67, you may use “Scout Luna” for the Name field. For the Location field enter the Scout release repository as specified below. http://download.eclipse.org/scout/releases/4.0.

After the Eclipse IDE has connected to the Scout repository, select the Scout feature Scout Application Development as shown in Figure 68. Then, move through the installation with the Next button. On the last installation step, accept the presented EPL terms by clicking on the appropriate radio button. To complete the installation, click the Finish button and accept the request for a restart of Eclipse. After the restart of the Eclipse IDE, you may add the Scout perspective using the Window ▸ Open Perspective ▸ Other …​ menu and selecting the Scout perspective from the presented list. Clicking on the Scout perspective button should then result in a state very similar to Figure 65.

After you can start your Eclipse Scout package you need to verify that Scout is working as intended. The simplest way to verify your Scout installation is to create a “Hello World” Scout project and run the corresponding Scout application as described in Chapter “Hello World” Tutorial.

According to the Tomcat setup installation for Windows.[64] download the package “32-bit/64-bit Windows Service Installer” from the Tomcat 7 download site. Then, start the installer and accept the proposed default settings.

For installing Tomcat on OS X systems download the “tar.gz” package from the Tomcat 7 download site. Then, follow the installation guide.[65] provided by Wolf Paulus.

For Linux systems download the “tar.gz” package from the Tomcat 7 download site. Then, follow the description of the Unix setup.[66] to run Tomcat as a deamon. If you use Ubuntu, you may want to follow the tutorial.[67] for downloading and installing Tomcat provided by Lars Vogel.

Tomcat’s installation directory follows the same organisation on all platforms. Here, we will only introduce the most important aspects of the Tomcat installation for the purpose of this book.

Note that some folders and many files of a Tomcat installation are not represented in Figure 70. We just want to provide a basic understanding of the most important parts to operate the web server in the context of this book. In the bin folder, the executable programs are contained, including scripts to start and stop the Tomcat instance.

The conf folder contains a set of XML and property configuration file. The file server.xml represents Tomcat’s main configuration file. It is used to configure general web server aspects such as the port number of its connectors for the client server communication. For the default setup, port number 8080 is used for the communication between clients applications and the web server. The file tomcat-users.xml contains a database of users, passwords and associated roles.

Folder logs contains various logfiles of Tomcat itself as well as host and web application log files. XXX need to provide more on what is where (especially application logs and exact setup to generate log entries from scout apps).

The folder needed for deploying web applications into a Tomcat instance is called webapps. It can be used as the target for copying WAR files into the web server. The installation of the WAR file then extracts its content into the corresponding directory structure as shown in Figure 70 in the case of the file helloworld_server.war.

Finally, folder work contains Tomcat’s runtime “cache” for the deployed web applications. It is organized according to the hierarchy of the engine (Catalina), the host (localhost), and the web application (helloworld_server).

Tomcat comes with the pre installed “Manager App”. This application is useful to manage web applications and perform tasks such as deploying a web application from a WAR file, or starting and stopping installed web applications. A comprehensive documentation for the “Manager App” can be found under the Tomcat homepage.[68]. Here we only show how to start this application from the hompage of a running Tomcat installation.

To access this application you can switch to the “Manager App” with a click on the corresponding button on the right hand side. The button can be found on the right hand side of Figure 69. Before you are allowed to start this application, you need to provide username and password credentials of a user associated with Tomcats’s manager-gui role.

To get at user names and passwords you can open file tomcat-users.xml located in Tomcat’s conf directory. In this file the active users with their passwords and associated roles are stored. See Listing [lst-tomcat.users] for an example. From the content of this file, we see that user admin has password s3cret and also posesses the necessary role manager-gui to access the “Manager App”. If file tomcat-users.xml does not contain any user with this role, you can simply add new user with this role to the existing users. Alternatively, you also can add the necessary role to an existing user. Just append a comma to the existing right(s) followed by the string manager-gui. Note that you will need to restart your Tomcat application after adapting the content of file tomcat-users.xml.

With working credentials you can now start the “Manager App” as described the “Hello World” tutorial in Section Deploying to Tomcat.

text needed

also mention apache StringUtils http://commons.apache.org/lang/api-2.3/org/apache/commons/lang/StringUtils.html

text needed

text needed

Existing Documentation

needs text

Excellent Eclipse IDE tutorial by L. Vogel http://www.vogella.com/articles/Eclipse/article.html.

What is OSGi: http://www.osgi.org/Technology/WhatIsOSGi What is Equinox: http://www.eclipse.org/equinox/

Server-side Equinox: http://www.eclipse.org/equinox/server/http_in_container.php

The web.xml, the lib/servletbridge.jar and eclipse/plugins/servlet, equinox and bla stuff

bundle example

needs text

needs text

release engineering artefacts vs runtime artefacts. start with runtime artefacts