Eclipse Scout

https://eclipsescout.github.io
Admin
Eclipse Scout is a Java and JavaScript framework for building modern, multi-tier business...
Tokens:217,897
Snippets:1,837
Trust Score:9.7
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start backend and frontend servers

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Commands to execute the application startup scripts for both the backend and UI servers.

```bash
cd /opt/helloscout/helloscout-server
bin/app.sh
cd /opt/helloscout/helloscout-ui
bin/app.sh
```

--------------------------------

### Start frontend server container

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-docker-container.html

Starts the frontend server container, overriding the scout.backendUrl property via an environment variable to point to the backend container name.

```bash
docker run -d -p 8082:8080 --pull always --network helloscout-network --name helloscout-ui -e scout_backendUrl=http://helloscout-server:8080 localhost:5000/helloscout-ui:1.0.0-latest
```

--------------------------------

### Register and start services

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Reloads the systemd daemon and enables the services to start automatically.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now helloscout-server
sudo systemctl enable --now helloscout-ui
```

--------------------------------

### Expected build output

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-docker-container.html

Example of the console output confirming successful image build and push.

```text
Built and pushed image as localhost:5000/helloscout-server, localhost:5000/helloscout-server:1.0.0-latest
```

--------------------------------

### Start and handle a JsForm

Source: https://eclipsescout.github.io/scout-docs/26.1/howtos/scout-classic/js-form-how-to.html

Instantiate the JsForm, provide input data, start the form, and process the output data after the form is stored.

```java
ExampleJsForm exampleJsForm = new ExampleJsForm();
exampleJsForm.setInputData(getExampleJsFormInputData());
exampleJsForm.start();
exampleJsForm.waitFor();
if (exampleJsForm.isFormStored()) {
  ExampleJsFormDo outputData = exampleJsForm.getOutputData();
  // ...
```

--------------------------------

### Initialize custom App in entry point (Listing 9)

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/user-interface/extensibility.html

Create an instance of CustomApp and call init() to start the application with the custom extensions.

```typescript
import CustomApp from './CustomApp';

let app = new CustomApp();
app.init();
```

--------------------------------

### Start backend server container

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-docker-container.html

Starts the backend server container on the shared network. The --pull always flag ensures the latest image is used.

```bash
docker run -d -p 8080:8080 --pull always --network helloscout-network --name helloscout-server localhost:5000/helloscout-server:1.0.0-latest
```

--------------------------------

### Verify Node.js installation

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/helloscout-js-fullstack.html

Check that Node.js is installed and on the PATH by running `node -v`. Expected output shows the version, e.g., v24.12.0.

```asciidoc
c:\> node -v
v24.12.0
```

--------------------------------

### Verify pnpm installation

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/helloscout-js-fullstack.html

Check that pnpm was installed successfully by running `pnpm -v`. Expected output shows the version, e.g., 10.26.1.

```asciidoc
c:\> pnpm -v
10.26.1
```

--------------------------------

### Clone the HelloScout repository

Source: https://eclipsescout.github.io/scout-docs/26.1/howtos/scout-js/flip-card-how-to.html

Clones the helloscout repository used as a base for the example.

```bash
git clone https://github.com/bsi-software/helloscout.git
```

--------------------------------

### Sample .gitignore file

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/one-day-tutorial.html

A starting point for excluding common build artifacts and dependency folders from Git tracking.

```text
# Git
*.orig

# Maven
target/
.surefire-*
.flattened-pom.xml

# Node
node_modules/
test-results/

# Do not check in any log files
*.log
```

--------------------------------

### Using ExampleDoEntityListDo with polymorphic subclasses

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/data-object.html

Example usage of the ExampleDoEntityListDo class, populating it with different concrete subclasses of AbstractExampleEntityDo.

```java
    ExampleDoEntityListDo entity = BEANS.get(ExampleDoEntityListDo.class);
    entity.withListAttribute(
        BEANS.get(ExampleEntity1Do.class)
            .withName1Ex("one-ex")
            .withName("one"),
        BEANS.get(ExampleEntity2Do.class)
            .withName2Ex("two-ex")
            .withName("two"));

    entity.withSingleAttribute(
        BEANS.get(ExampleEntity1Do.class)
            .withName1Ex("single-one-ex")
            .withName("single-one"));
```

--------------------------------

### Create a basic extension class (MyExtension)

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/user-interface/extensibility.html

Subclass Extension and implement init() to register the function to extend. This example extends StringField.prototype._init.

```typescript
import {Extension, StringField} from '@eclipse-scout/core';

export class MyExtension extends Extension {
  init() {
    this.extend(StringField.prototype, '_init');
  }
}
```

--------------------------------

### Access attributes in ExampleMapEntityDo

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/data-object.html

Demonstrates how to populate and retrieve attributes from a map-like data object using get and all methods.

```java
    ExampleMapEntityDo mapEntity = BEANS.get(ExampleMapEntityDo.class);
    mapEntity.put("mapAttribute1",
        BEANS.get(ExampleEntityDo.class)
            .withName("Example")
            .withValues(1, 2, 3, 4, 5));
    mapEntity.put("mapAttribute2",
        BEANS.get(ExampleEntityDo.class)
            .withName("Example")
            .withValues(6, 7, 8, 9));

    ExampleEntityDo attr1 = mapEntity.get("mapAttribute1"); (1)
    Map<String, ExampleEntityDo> allAttributes = mapEntity.all(); (2)
```

--------------------------------

### REST resource implementation

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/rest.html

Defines a Jakarta REST resource for the path "example", responding to GET requests with a JSON entity.

```java
@Path("example")
public class ExampleResource implements IRestResource {

  @GET
  @Path("{id}")
  @Produces(MediaType.APPLICATION_JSON)
  public ExampleEntityDo getExampleEntity(@PathParam("id") String id) {
    return BEANS.get(ExampleEntityDo.class)
        .withName("example-" + id)
        .withValues(1);
  }
}
```

--------------------------------

### Get GlobalOpenTelemetry for custom metrics

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/observability.html

Use this snippet to obtain the global OpenTelemetry instance and start adding custom metrics directly in production code. The comment points to the official manual for further metric instrumentation steps.

```java
OpenTelemetry openTelemetry = GlobalOpenTelemetry.get();
// continue with https://opentelemetry.io/docs/instrumentation/java/manual/#metrics.
```

--------------------------------

### Create ExampleEntityDo instance

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/data-object.html

Demonstrates creating a new instance of a data object using the fluent-style API provided by convenience methods.

```java
    ExampleEntityDo entity = BEANS.get(ExampleEntityDo.class)
        .withName("Example")
        .withValues(1, 2, 3, 4, 5);
```

--------------------------------

### Install pnpm globally

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/helloscout-js-fullstack.html

Install pnpm 8 as the package manager for Scout using npm. The command installs pnpm@10.26.1 globally.

```asciidoc
npm install -g pnpm@10.26.1
```

--------------------------------

### Build the application with Maven

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Execute this command in the parent module to compile, test, and bundle the application into ZIP files.

```bash
mvn clean verify
```

--------------------------------

### Create deployment directory

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Creates the directory /opt/helloscout where the application will be placed.

```bash
mkdir /opt/helloscout
```

--------------------------------

### Install Java 25

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Installs the OpenJDK 25 package required to run Scout applications.

```bash
apt install openjdk-25-jdk
```

--------------------------------

### SQL session variable binding example

Source: https://eclipsescout.github.io/scout-docs/26.1/migration/migration-guide.html

Example of a SQL query that previously relied on automatic session variable binding.

```sql
SELECT :userId;
```

--------------------------------

### Configure CSP directives in config.properties

Source: https://eclipsescout.github.io/scout-docs/26.1/migration/migration-guide.html

Example showing how to define CSP directives for all entry points and specific entry points like login.html.

```properties
# directive valid for all entry points
scout.cspDirective[script-src]=https://my.cdn.org/

# additional url only for login.html
scout.cspDirective[script-src#login.html]=https://login.cdn.org/
```

--------------------------------

### Check frontend server logs

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-docker-container.html

Displays the logs for the frontend container to verify successful startup.

```bash
docker logs helloscout-ui
```

--------------------------------

### Register beans using IPlatformListener

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/platform.html

Demonstrates how to register beans during application startup by implementing the IPlatformListener interface and listening for the BeanManagerPrepared state.

```java
public class RegisterBeansListener implements IPlatformListener {
  @Override
  public void stateChanged(PlatformEvent event) {
    if (event.getState() == State.BeanManagerPrepared) {
      // register the class directly
      BEANS.getBeanManager().registerClass(BeanSingletonClass.class);

      // Or register with meta information
      BeanMetaData beanData = new BeanMetaData(BeanClass.class).withApplicationScoped(true);
      BEANS.getBeanManager().registerBean(beanData);
    }
  }
}
```

--------------------------------

### Create and configure SmtpServerConfig

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/smtp-helper.html

Shows how to instantiate and configure an SmtpServerConfig using the BEANS.get() method and fluent with* methods. The example sets host, port, authentication, and TLS options.

```java
@SuppressWarnings("unused")
SmtpServerConfig smtpServerConfig = BEANS.get(SmtpServerConfig.class)
    .withHost("mail.example.com")
    .withPort(465)
    .withUsername("smtpuser")
    .withPassword("smtpuserpwd")
    .withUseAuthentication(true)
    .withUseSmtps(true)
    .withUseStartTls(true);
```

--------------------------------

### Check backend server logs

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-docker-container.html

Displays the logs for the backend container to verify successful startup.

```bash
docker logs helloscout-server
```

--------------------------------

### Install handlers for authentication and logging

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/jax-ws.html

Override execInstallHandlers to add handlers to the handler chain. Handlers are invoked in the order added. By default, no handler is installed. The method is invoked upon preemptive creation of the port, so no assumptions about the calling thread can be made. If a handler requires a different RunContext, annotate it with @RunWithRunContext.

```java
public class PingWebServiceClient2 extends AbstractWebServiceClient<PingWebService, PingWebServicePortType> {

  @Override
  protected void execInstallHandlers(List<jakarta.xml.ws.handler.Handler<?>> handlerChain) {
    handlerChain.add(BEANS.get(BasicAuthenticationHandler.class));
    handlerChain.add(BEANS.get(LogHandler.class));
  }
}
```

--------------------------------

### Check application logs

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/run-as-service.html

Commands to display the plain text logs for both the backend and UI servers to verify successful startup.

```bash
cat /opt/helloscout/helloscout-server/logs/app.plain.log
cat /opt/helloscout/helloscout-ui/logs/app.plain.log
```

--------------------------------

### Configure scout.externalBaseUrl

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/platform.html

Example of setting the absolute base URL for the web application.

```properties
scout.externalBaseUrl=https://www.my-company.com/my-scout-application/.
```

--------------------------------

### Implement IPlatformListener to react to platform startup

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/platform.html

Create a platform listener by implementing IPlatformListener and overriding stateChanged. The listener is automatically a bean and does not need registration. It is notified when the platform state changes, e.g., when the platform has been started completely.

```java
public class MyListener implements IPlatformListener {
  @Override
  public void stateChanged(PlatformEvent event) {
    if (event.getState() == State.PlatformStarted) {
      // do some work as soon as the platform has been started completely
    }
  }
}
```

--------------------------------

### hello.js - Define Desktop class and initialize Scout app

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/helloscout-cdn.html

JavaScript file that defines a custom Desktop class extending scout.Desktop. It provides a JSON model with a form containing a name field and a greet button, and handles the button click to show a message box. It registers the Desktop factory and initializes the Scout app with bootstrap URLs for texts and locales.

```javascript
class Desktop extends scout.Desktop {

  constructor() {
    super();
  }

  _jsonModel() {
    return {
      objectType: 'Desktop',
      navigationHandleVisible: false,
      navigationVisible: false,
      headerVisible: false,
      views: [
        {
          objectType: 'Form',
          displayHint: 'view',
          rootGroupBox: {
            objectType: 'GroupBox',
            borderDecoration: scout.GroupBox.BorderDecoration.EMPTY,
            fields: [
              {
                id: 'NameField',
                objectType: 'StringField',
                label: 'Name'
              },
              {
                id: 'GreetButton',
                objectType: 'Button',
                label: 'Say Hello',
                keyStroke: 'enter',
                processButton: false
              }
            ]
          }
        }
      ]
    };
  }

  _init(model) {
    super._init(model);
    this.widget('GreetButton').on('click', event => {
      let name = this.widget('NameField').value || 'stranger';
      scout.MessageBoxes.openOk(this.session.desktop, `Hello ${name}!`);
    });
  }
}

scout.addObjectFactories({
  'Desktop': () => new Desktop()
});

new scout.App().init({
  bootstrap: {
    textsUrl: 'https://unpkg.com/@eclipse-scout/core@{node-version}/dist/texts.json',
    localesUrl: 'https://unpkg.com/@eclipse-scout/core@{node-version}/dist/locales.json'
  }
});
```

--------------------------------

### Configure scout.cspDirectiveAppend

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/platform.html

Example of appending an image source directive to the Content Security Policy.

```properties
scout.cspDirectiveAppend[img-src]=https://additional.host.org
```

--------------------------------

### Configure scout.app.keyStorePath

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/common-concepts/platform.html

Example values for the key store path property, which enables the HTTPS connector.

```text
`classpath:/dev/my-https.jks` or `file:///C:/Users/usr/Desktop/my-store.jks` or `C:/Users/usr/Desktop/my-store.jks`.
```

--------------------------------

### Initialize src/helloworld.ts entry point

Source: https://eclipsescout.github.io/scout-docs/26.1/getstarted/helloscout-js.html

This file registers the Desktop factory and the helloworld namespace before initializing the App instance with text and locale URLs.

```typescript
import {App, ObjectFactory, scout} from '@eclipse-scout/core';
import {Desktop} from './desktop/Desktop'
import {HelloForm} from './greeting/HelloForm'

scout.addObjectFactories({
  'Desktop': () => new Desktop()
});

ObjectFactory.get().registerNamespace('helloworld', {
  HelloForm
});

new App().init({
  bootstrap: {
    textsUrl: 'texts.json',
    localesUrl: 'locales.json'
  }
});
```

--------------------------------

### Client-side multipart request

Source: https://eclipsescout.github.io/scout-docs/26.1/technical-guide/working-with-data/rest.html

Example of creating and sending a multipart message using MultipartMessage and WebTarget.

```java
  public void pushContent(BinaryResource resource, String displayText) {
    MultipartMessage multipartMessage = BEANS.get(MultipartMessage.class)
        .addPart(MultipartPart.ofFile("resource", resource.getFilename(), new ByteArrayInputStream(resource.getContent())))
        .addPart(MultipartPart.ofField("displayText", displayText));

    WebTarget target = helper()
        .target(RESOURCE_PATH)
        .path("/content");

    Response response = target.request()
        .accept(MediaType.APPLICATION_JSON)
        .post(multipartMessage.toEntity());
    response.close();
  }
```
Tokens:
Raw