Platform

This document is referring to a past Scout release. Please click here for the recent version.

Scout contains a platform which provides basic functionality required by many software applications. The following list gives some examples for which tasks the platform is responsible for:

Application Lifecycle Management
Object Instance Management (Bean Management)
Configuration Management
Application Inventory

Application Lifecycle

The lifecycle of a Scout application is controlled by implementations of org.eclipse.scout.rt.platform.IPlatform. This interface contains methods to start and stop the application and to retrieve the Bean Manager associated with this application. The class org.eclipse.scout.rt.platform.Platform provides access to the current platform instance. On first access the platform is automatically created and started.

During its startup, the platform transitions through several states. Depending on the state of the platform some components may already be initialized and ready to use while others are not available yet.

See enum org.eclipse.scout.rt.platform.IPlatform.State for a description of each state and what may be used in a certain state.

Platform Listener

To participate in the application startup or shutdown a platform listener can be created. For this a class implementing org.eclipse.scout.rt.platform.IPlatformListener must be created. The listener is automatically a bean and must therefore not be registered anywhere. See Bean Manager to learn more about bean management in Scout and how the listener becomes a bean. As soon as the state of the platform changes the listener will be notified.

Listing 1. A listener that will do some work as soon as the platform has been started.

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
    }
  }
}

As platform listeners may run as part of the startup or shutdown not the full Scout platform may be available. Depending on the state some tasks cannot be performed or some platform models are not available yet!

Class Inventory

Scout applications use an inventory containing the classes available together with some meta data about them. This allows finding classes available on the classpath by certain criteria:

All subclasses of a certain base class (also known as type hierarchy)
All classes having a specific annotation.

This class inventory can be accessed as described in listing Listing 2.

Listing 2. Access the Scout class inventory.

IClassInventory classInventory = ClassInventory.get();

// get all classes below IService
Set<IClassInfo> services = classInventory.getAllKnownSubClasses(IService.class);

// get all classes having a Bean annotation (directly on them self).
Set<IClassInfo> classesHavingBeanAnnot = classInventory.getKnownAnnotatedTypes(Bean.class);

scout.xml

In its static initializer, the ClassInventory collects classes in projects containing a resource called META-INF/scout.xml.

Scanning all classes would be unnecessarily slow and consume too much memory. The file scout.xml is just an empty xml file. Scout itself also includes scout.xml files in all its projects.

The format XML was chosen to allow adding exclusions in large projects, but this feature is not implemented right now.

It is recommended to add an emtpy scout.xml file into the META-INF folder of your projects, such that the classes are available in the 'ClassInventory'.

Scout uses Jandex ^[1] to build the class inventory. The meta data to find classes can be pre-computed during build time into an index file describing the contents of the jar file. See the jandex project for details.

Bean Manager

The Scout bean manager is a dynamic registry for beans. Beans are normal Java classes usually having some meta data describing the characteristics of the class.

The bean manager can be changed at any time. This means beans can be registered or unregistered while the application is running. For this the bean manager contains methods to register and unregister beans. Furthermore, methods to retrieve beans are provided.

The next sections describe how beans are registered, the different meta data of beans, how instances are created, how they can be retrieved and finally how the bean decoration works.

Bean registration

Usually beans are registered during application startup. The application startup can be intercepted using platform listeners as described in Platform Listener.

Listing 3. A listener that registers a bean (direct class or with meta data).

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);
    }
  }
}

There is also a predefined bean registration built into the Scout runtime. This automatically registers all classes having an org.eclipse.scout.rt.platform.@Bean annotation. Therefore, it is usually sufficient to only annotate a class with @Bean to have it available in the bean manager as shown in listing Listing 4.

Listing 4. A normal bean

@Bean
public class BeanClass {
}

As the @Bean annotation is an java.lang.annotation.@Inherited annotation, this automatically registers all child classes too. This means that also interfaces may be @Bean annotated making all implementations automatically available in the bean manager! Furthermore, other annotations may be @Bean annotated making all classes holding these annotations automatically to beans as well.

If you inherit a @Bean annotation from one of you super types but don’t want to be automatically registered into the bean manger you can use the org.eclipse.scout.rt.platform.@IgnoreBean annotation. Those classes will then be skipped.

@TunnelToServer

There is a built-in annotation org.eclipse.scout.rt.shared.@TunnelToServer. Interfaces marked with this annotation are called on the server. The server itself ignores this annotation.

To achieve this a bean is registered on client side for each of those interfaces. Because the platform cannot directly create an instance for these beans a specific producer is registered which creates a proxy that delegates the call to the server. Please note that this annotation is not inherited. Therefore, if an interface extends a tunnel-to-server interface and the new methods of this interface should be called on the server as well the new child interface has to repeat the annotation!

The proxy is created only once for a specific interface bean.

Bean Scopes

The most important meta data of a bean is the scope. It describes how many instances of a bean can exist in a single application. There are two different possibilities:

Unlimited instances: Each bean retrieval results in a new instance of the bean. This is the default.
Only one instance: There can only be one instance by Scout platform. From an application point of view this can be seen as singleton. The instance is created on first use and each subsequent retrieval of the bean results in this same cached instance.

As like all bean meta data this characteristic can be provided in two different ways:

With a Java annotation on the bean class as shown in the listing Listing 5.
With bean meta data as shown in listing Listing 3.

Listing 5. An application scoped bean using annotations

@ApplicationScoped
public class BeanSingletonClass {
}

So the Java annotation org.eclipse.scout.rt.platform.@ApplicationScoped describes a bean having singleton characteristics.

Also @ApplicationScoped is an @Inherited annotation. Therefore, all child classes automatically inherit this characteristic like with the @Bean annotation.

Bean Creation

It is not only possible to influence the number of instances to be created (see Bean Scopes), but also to create beans eagerly, execute methods after creation (like constructors) or to delegate the bean creation completely. These topics are described in the next sections.

Eager Beans

By default beans are created on each request. An exception are the beans marked to be application scoped (as shown in Bean Scopes). Those beans are only created on first request (lazy). This means if a bean is never requested while the application is running, there will never be an instance of this class.

But sometimes it is necessary to create beans already at the application startup (eager). This can be done by marking the bean as org.eclipse.scout.rt.platform.@CreateImmediately. All classes holding this annotation must also be marked as @ApplicationScoped! These beans will then be created as part of the application startup.

Constructors

Beans must have empty constructors so that the bean manager can create instances. But furthermore it is possible to mark methods with the javax.annotation.@PostConstruct annotation. Those methods must have no parameters and will be called after instances have been created.

When querying the bean manager for an application scoped bean, it will always return the same instance. However, the constructor of an application scoped bean may run more than once, whereas a method annotated with @PostConstruct in an application scoped been is guaranteed to run exactly once.

Bean Retrieval

To retrieve a bean the class org.eclipse.scout.rt.platform.BEANS should be used. This class provides (amongst others) the following methods:

Listing 6. How to get beans.

BeanSingletonClass bean = BEANS.get(BeanSingletonClass.class);
BeanClass beanOrNull = BEANS.opt(BeanClass.class);

The get() method throws an exception if there is not a single bean result. So if no bean can be found or if multiple equivalent bean candidates are available this method fails!
The opt() method requires a single or no bean result. It fails if multiple equivalent bean candidates are available and returns null if no one can be found.
The all() method returns all beans in the correct order. The list may also contain no beans at all.

There are now two more annotations that have an effect on which beans are returned if multiple beans match a certain class. Consider the following example bean hierarchy:

Figure 1. A sample bean hierarchy.

In this situation 4 bean candidates are available: MyServiceImpl, MyServiceMod, MySpecialVersion and AnotherVersion. But which one is returned by BEANS.get(IMyService.class)? Or by BEANS.get(MySpecialVersion.class)? This can be influenced with the org.eclipse.scout.rt.platform.@Order and org.eclipse.scout.rt.platform.@Replace annotations. The next sections describe the idea behind these annotations and gives some examples.

@Order

This annotation works exactly the same as in the Scout user interface where it brings classes into an order. It allows to assign a double value to a class. All beans of a certain type are sorted according to this value in ascending order. This means a low order value is equivalent with a low position in a list (come first).

Please note that the @Order annotation is not inherited so that each bean must declare its own value where it fits in.

The @Order annotation value may be inherited in case it replaces. See the next section for details.

If a bean does not declare an order value, the default of 5000 is used. Scout itself uses orders from 4001 to 5999. So for user applications the value 4000 and below can be used to declare more important beans. For testing bean mocks the value -10'000 can be used which then usually comes before each normal Scout or application bean.

@Replace

The @Replace annotation can be set to beans having another bean as super class. This means that the original bean (the super class) is no longer available in the Scout bean manager and only the new child class is returned.

If the replacing bean (the child class) has no own @Order annotation defined but the replaced bean (the super class) has an @Order value, this order is inherited to the child. This is the only special case in which the @Order annotation value is inherited!

Examples

The next examples use the bean situation as shown in figure Figure 1. In this situation the bean manager actually contains 3 beans:

AnotherVersion with @Order of 4000. This bean has no own order and would therefore get the default order of 5000. But because it is replacing another bean it inherits its order.
MyServiceMod with @Order of 4500. This bean declares its own order.
MyServiceImpl with @Order of 5000. This bean gets the default order of 5000 because it does not declare an order.

The bean MySpecialVersion is not part of the bean manager because it has been replaced by AnotherVersion.

BEANS.get(IMyService.class): Returns AnotherVersion instance. The result cannot be an exact match because the requested type is an interface. Therefore, of all candidates there is one single candidate with the lowest order (comes first).
BEANS.get(MyServiceImpl.class): Returns MyServiceImpl because there is an exact match available.
BEANS.get(MySpecialVersion.class): Returns AnotherVersion. The result cannot be an exact match because there is no exact bean with this class in the bean manager (MySpecialVersion has been replaced). Therefore, only AnotherVersion remains as candidate in the hierarchy below MySpecialVersion.
BEANS.get(MyServiceMod.class): Returns MyServiceMod because there is no other candidate.
BEANS.all(IMyService.class): Returns a list with all beans sorted by @Order. This results in: AnotherVersion, MyServiceMod, MyServiceImpl.

If MyServiceMod would have no @Order annotation, there would be two bean candidates available with the same default order of 5000: MyServiceImpl and MyServiceMod. In this case a call to BEANS.get(IMyService.class) would fail because there are several equivalent candidates. Equivalent candidates means they have the same @Order value and the system cannot decide which one is the right one.

Bean Decoration

Bean decorations allow to wrap interfaces with a proxy to intercept each method call to the interface of a bean and apply some custom logic. For this a IBeanDecorationFactory has to be implemented. This is one single factory instance for the entire application. It decides which decorators are created for a bean request. The factory is asked for decorators on every bean retrieval. This allows to write bean decoration factories depending on dynamic conditions.

As bean decoration factories are beans themselves, it is sufficient to create an implementation of org.eclipse.scout.rt.platform.IBeanDecorationFactory and to ensure this implementation is used (see Bean Retrieval). This factory receives the bean to be decorated and the originally requested bean class to decide which decorators it should create. In case no decoration is required the factory may return null. Then the original bean is used without decorations.

Decorations are only supported if the class obtained by the bean manager (e.g. by using BEANS.get()) is an interface!

It is best practice to mark all annotations that are interpreted in the bean decoration factory with the annotation org.eclipse.scout.rt.platform.@BeanInvocationHint. However, this annotation has no effect at runtime and is only for documentation reasons.

The sample in listing Listing 7 wraps each call to the server with a profiler decorator that measures how long a server call takes.

Listing 7. Bean decoration example.

@Replace
public class ProfilerDecorationFactory extends SimpleBeanDecorationFactory {
  @Override
  public <T> IBeanDecorator<T> decorate(IBean<T> bean, Class<? extends T> queryType) {
    return new BackendCallProfilerDecorator<>(super.decorate(bean, queryType));
  }
}

public class BackendCallProfilerDecorator<T> implements IBeanDecorator<T> {

  private final IBeanDecorator<T> m_inner;

  public BackendCallProfilerDecorator(IBeanDecorator<T> inner) {
    m_inner = inner;
  }

  @Override
  public Object invoke(IBeanInvocationContext<T> context) {
    final String className;
    if (context.getTargetObject() == null) {
      className = context.getTargetMethod().getDeclaringClass().getSimpleName();
    }
    else {
      className = context.getTargetObject().getClass().getSimpleName();
    }

    String timerName = className + '.' + context.getTargetMethod().getName();
    TuningUtility.startTimer();
    try {
      if (m_inner != null) {
        // delegate to the next decorator in the chain
        return m_inner.invoke(context);
      }
      // forward to real bean
      return context.proceed();
    }
    finally {
      TuningUtility.stopTimer(timerName);
    }
  }
}

Destroy Beans

Application scoped beans can declare methods annotated with javax.annotation.@PreDestroy. These methods will be called when the Scout platform is stopping. The methods may have any visibility modifier but must not be static and must not declare any parameters. If such a pre-destroy method throws an exception, the platform will continue to call all other pre-destroy methods (even methods on the same bean).

Please note that pre-destroy methods are only called for application-scoped beans that already have created their instance.

Pre-destroy methods inherited from super classes are always called after the ones from the class itself. Methods that are overridden are only called on the leaf class. Private methods are always called (because they cannot be overridden). The order in which multiple methods in the same declaring class are called is undefined.

Configuration Management

Applications usually require some kind of configuration mechanism to use the same binaries in a different environment or situation. Scout applications provide a configuration mechanism using properties files ^[2].

For each property a class cares about default values and value validation. These classes share the org.eclipse.scout.rt.platform.config.IConfigProperty interface and are normal application scoped beans providing access to a specific configuration value as shown in listing Listing 8. If the property class is an inner class it has to be defined as a static class with the static modifier.

Listing 8. A configuration property of type Long.

import org.eclipse.scout.rt.platform.config.AbstractLongConfigProperty;

/**
 * Property of data type {@link Long} with key 'my.custom.timeout' and default value '3600L'.
 */
public class MyCustomTimeoutProperty extends AbstractLongConfigProperty {

  @Override
  public String getKey() {
    return "my.custom.timeout"; (1)
  }

  @Override
  public String description() {
    return "Description of the custom timeout property. The default value is 3600.";
  }

  @Override
  public Long getDefaultValue() {
    return 3600L; (2)
  }
}

1	key
2	default value

To read the configured value you can use the CONFIG class as demonstrated in Listing 9.

Listing 9. Read the configured value in your code.

Long value = CONFIG.getPropertyValue(MyCustomTimeoutProperty.class);

Property resolution

The given property key is searched in the following environments:

In the system properties (java.lang.System.getProperty(String)).
In the environment variables of the system (java.lang.System.getenv(String)).
In the properties file. The properties file can be
1. a file on the local filesystem where the system property with key config.properties holds an absolute URL to the file or
2. a file on the classpath with path /config.properties (recommended).
If none of the above is found, the default value of the property is applied.

Supported formats are simple key-value pairs, list values and map values. For more details about the format please refer to the JavaDoc of the org.eclipse.scout.rt.platform.config.PropertiesHelper class.

Since the environment variable names are more restrictive in many shells and systems than the property names in Java, overriding a property containing a dot/period (.) with an environment variable would not be possible. To still allow overriding of such properties, the following lookup rules are applied in-order to find a matching environment variable:

An exact match of your property key (my.property)
A match where periods are replaced by underscores (my_property)
An uppercase match of your property key (MY.PROPERTY)
An uppercase match where periods are replaced by underscores (MY_PROPERTY)

When it comes to working with mapped config properties (subclasses of org.eclipse.scout.rt.platform.config.AbstractMapConfigProperty), there’s also some special mechanic to consider in terms of providing or overriding property map values using environment variables. Since it is not possible to reliably retrieve the original map key from an environment variable (again, due to the restrictions mentioned above), property map values may be supplied using environment variables whose value is a JSON object string:

my_map_property={"map-key-01": "value-01", "map-key-02": "value-02", "map-key-03": null}

The following rules apply, when such environment variables are read: * property map key/value pairs are added from the JSON object to the property map, overriding keys already being defined by sources of lower precedence (e.g. config.properties file) * a JSON object attribute value of "null" will remove a key potentially being defined by sources of lower precedence

The parsing of JSON object strings is abstracted away using the new org.eclipse.scout.rt.platform.config.IJsonPropertyReader interface as parsing JSON strings is not implemented in the platform itself. However, there is a default implementation of this interface available in org.eclipse.scout.rt.dataobject which uses the org.eclipse.scout.rt.platform.dataobject.IDataObjectMapper feature to deserialize the JSON string into a Java Map. In order to use this, an implementation of the IDataObjectMapper interface is also required (e.g. org.eclipse.scout.rt.jackson.dataobject.JacksonDataObjectMapper). So in case you want to use this feature, you have to define * org.eclipse.scout.rt:org.eclipse.scout.rt.dataobject * org.eclipse.scout.rt:org.eclipse.scout.rt.jackson as new dependencies of your application aggregator module (if they are not already present).

A properties file may import other config files from the classpath or any other absolute URL. This is done using the special key import. It can be a single value or a list or map (e.g. import[anyKey or number]:

import[0]=classpath:myConfigs/other.properties
import[1]=file:/C:/path/to/my/settings.properties
import[2]=file:${catalina.base}/conf/db_connection.properties

Scout already has some config properties. For a list and the corresponding documentation see Scout Config Properties.

Additional examples

Because the property classes are managed by the bean manager, you can use all the mechanisms to change the behavior (@Replace in particular).

Listing 10 demonstrates how you can use the @Replace annotation to change the existing ApplicationNameProperty class. The value is no longer fetched via the config mechanism, because the getValue(String) method is overridden. In this case a fixed value is returned.

Listing 10. Property class providing a constant value.

import org.eclipse.scout.rt.platform.IgnoreBean;
import org.eclipse.scout.rt.platform.Replace;
import org.eclipse.scout.rt.platform.config.PlatformConfigProperties.ApplicationNameProperty;

@Replace
public class ApplicationNameConstant extends ApplicationNameProperty {
  @Override
  protected String readFromSource(String namespace) {
    return "Contacts Application";
  }
}

The next example presented in Listing 11 uses the same idea. In this case, the getKey() method is overridden to read the value from another key as demonstrated is the Listing 12.

Listing 11. Property class reading the value from another key.

import org.eclipse.scout.rt.platform.IgnoreBean;
import org.eclipse.scout.rt.platform.Replace;
import org.eclipse.scout.rt.platform.config.PlatformConfigProperties.ApplicationNameProperty;

@Replace
public class ApplicationNamePropertyRedirection extends ApplicationNameProperty {

  @Override
  public String getKey() {
    return "myproject.applicationName";
  }
}

Listing 12. Read the configured value in your code.

### Redirected Application Config
myproject.applicationName=My Project Application

Configuration validation

During the Platform startup all classes implementing the interface org.eclipse.scout.rt.platform.config.IConfigurationValidator are asked to validate configuration provided in the config.properties files. If there is at least one IConfigurationValidator that accepts a given key-value-pair the configuration is considered to be valid. Otherwise, the platform will not start.

The concrete implementation org.eclipse.scout.rt.platform.config.ConfigPropertyValidator will also check if a configured value matches the default value. In case it does an info message (warn in development mode) will be logged but the platform will still start. To minimize configuration files such entries should be removed from config.properties files.

Scout Config Properties

scout.application.name

The display name of the application. Used e.g. in the info form and the diagnostic views. The default value is unknown.

Data type: String

scout.application.version

The application version as displayed to the user. Used e.g. in the info form and the diagnostic views. The default value is 0.0.0.

Data type: String

scout.auth.anonymousEnabled

Specifies if the AnonymousAccessController is enabled. Therefore, if a security filter uses this controller no login is required.

Data type: Boolean

scout.auth.cookieEnabled

Specifies if the CookieAccessController is enabled.

Data type: Boolean

scout.auth.cookieMaxAge

If the CookieAccessController is enabled, specifies the maximum age in seconds for the cookie.

A positive value indicates that the cookie will expire after that many seconds have passed.

A negative value means that the cookie is not stored persistently and will be deleted when the Web browser exits. A zero value causes the cookie to be deleted.

The default value is 10 hours.

Data type: Long

scout.auth.cookieName

If the CookieAccessController is enabled, specifies the name for the cookie.

The name must conform to RFC 2109. However, vendors may provide a configuration option that allows cookie names conforming to the original Netscape Cookie Specification to be accepted.

By default sso.user.id is used as cookie name.

Data type: String

scout.auth.cookieSessionValidateSecure

Specifies if the UI server should ensure a secure cookie configuration of the webapp.

If enabled the application validates that the httpOnly and Secure flags are set in the cookie configuration in the web.xml.

This property should be disabled if no secure connection (https) is used to the client browser (not recommended).

The default value is true.

Data type: Boolean

scout.auth.credentials

Specifies the known credentials (username & passwords) of the org.eclipse.scout.rt.platform.security.ConfigFileCredentialVerifier.

Credentials are separated by semicolon. Username and password information are separated by colon. Usernames are case-insensitive, and it is recommended that they should only consist of ASCII characters. Plain text passwords are case-sensitive.

By default the password information consists of Base64 encoded salt followed by a dot followed by the Base64 encoded SHA-512 hash of the password (using UTF-16).

Example:

scout.auth.credentials=username1:base64EncodedSalt.base64EncodedPasswordHash;username2:base64EncodedSalt.base64EncodedPasswordHash

To create a salt and hash tuples based on a clear text password use the org.eclipse.scout.rt.platform.security.ConfigFileCredentialVerifier.main() method that can be invoked from the command line.

If scout.auth.credentialsPlaintext is set to true the password information just consists of the cleartext password.

Data type: String

scout.auth.credentialsPlaintext

Specifies if the passwords specified in property scout.auth.credentials is plaintext (not recommended) or hashed. A value of false indicates hashed passwords which is the default.

Data type: Boolean

scout.auth.privateKey

Specifies the Base64 encoded private key for signing requests from the UI server to the backend server. By validating the signature the server can ensure the request is trustworthy.

Furthermore, the CookieAccessController uses this private key to sign the cookie.

New public-private-key-pairs can be created by invoking the class org.eclipse.scout.rt.platform.security.SecurityUtility on the command line.

Data type: Base64 encoded String

scout.auth.publicKey

Specifies the Base64 encoded public key used to validate signed requests on the backend server. The public key must match the private key stored in the property scout.auth.privateKey on the UI server.

New public-private-key-pairs can be created by invoking the class org.eclipse.scout.rt.platform.security.SecurityUtility on the command line.

Data type: Base64 encoded String

scout.auth.tokenTtl

Number of milliseconds a signature on a request from the UI server to the backend server is valid (TTL for the authentication token). If a request is not received within this time, it is rejected.

By default this property is set to 10 minutes.

Data type: Long >= 0

scout.backendUrl

The URL of the scout backend server (without any servlets).

Example:

scout.backendUrl=http://localhost:8080

By default this property is null.

Data type: String

scout.client.jobCompletionDelayOnSessionShutdown

Specifies the maximal time (in seconds) to wait until running jobs are cancelled on session shutdown.

The default value is 10 seconds.

Data type: Long >= 0

scout.client.memoryPolicy

Specifies how long the client keeps fetched data before it is discarded. One of small, medium or large. The default value is large.

Data type: String

scout.client.notificationSubject

Technical subject under which received client notifications are executed.

By default notification-authenticator is used.

Data type: Subject name as String

scout.client.testingSessionTtl

Testing client session expiration in milliseconds. The default value is 1 day.

Data type: Long >= 0

scout.client.userArea

User data area (e.g. in the user home) to store user preferences. If nothing is specified the user home of the operating system is used. By default no user home is set.

Data type: String

scout.clientnotification.chunkSize

The maximum number of client notifications that are consumed at once. The default is 30.

Data type: Integer >= 0

scout.clientnotification.maxNotificationBlockingTimeOut

The maximum amount of time in millisecons a consumer blocks while waiting for new notifications. The default is 10 seconds.

Data type: Integer >= 0

scout.clientnotification.nodeQueueCapacity

Capacity of the client notification queue. If maximum capacity is reached, notification messages are dropped. The default value is 200.

Data type: Integer >= 0

scout.clientnotification.notificationQueueExpireTime

If no message is consumed for the specified number of milliseconds, client notification queues (with possibly pending notifications) are removed.

This avoids overflows and unnecessary memory consumption. Old queues may exist if a node does not properly unregister (e.g. due to a crash).

The default value is 10 minutes.

Data type: Integer >= 0

scout.clustersync.user

Technical subject under which received cluster sync notifications are executed. The default value is system.

Data type: String

scout.createTunnelToServerBeans

Specifies if the Scout platform should create proxy beans for interfaces annotated with TunnelToServer. Calls to beans of such types are then tunneled to the Scout backend.

By default this property is enabled if the property scout.servicetunnel.targetUrl is set.

Data type: Boolean

scout.cspDirective

Configures individual Content Security Policy (CSP) directives.

See Content Security Policy Level 2 and the Bean org.eclipse.scout.rt.server.commons.servlet.ContentSecurityPolicy for more details.

The value must be provided as a Map.

Example:

scout.cspDirective[img-src]=`self` data: 'self' data: https://media.example.com

Data type: Map

scout.cspEnabled

Enable or disable Content Security Policy (CSP) headers. The headers can be modified by replacing the bean org.eclipse.scout.rt.server.commons.servlet.ContentSecurityPolicy or using the property scout.cspDirective.

Data type: Boolean

scout.cspExclusions

A list of regex strings. If the pathInfo of the request matches one of these strings the csp headers won`t be set. This property only has an effect if csp is enabled, see scout.cspEnabled.

Data type: List

scout.devMode

Property to specify if the application is running in development mode. Default is false.

Data type: Boolean

scout.externalBaseUrl

Absolute URL to the deployed http(s):// base of the web-application. The URL should include proxies, redirects, etc.

Example:

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

This URL is used to replace <scout:base /> tags.

Data type: String

scout.healthCheckRemoteUrls

Comma separated list of URLs the RemoteHealthChecker should access.

By default no URLs are set.

Data type: List

scout.http.connectionTtl

Specifies the maximum lifetime in milliseconds for kept alive connections of the Apache HTTP client. The default value is 1 hour.

Data type: Integer

scout.http.ignoreProxyPatterns

Configure the proxy ignore list for the ConfigurableProxySelector. If a URI matches the pattern no proxy connection is used.

By default no proxy is configured.

Example:

scout.http.ignoreProxyPatterns[0]=https?://localhost(?::\d+)?(?:/.*)?
scout.http.ignoreProxyPatterns[1]=...

Data type: List

scout.http.keepAlive

Enable/disable HTTP keep-alive connections.

The default value is defined by the system property http.keepAlive or true if the system property is undefined.

Data type: Boolean

scout.http.maxConnectionsPerRoute

Configuration property to define the default maximum connections per route of the Apache HTTP client. The default value is 32.

Data type: Integer

scout.http.maxConnectionsTotal

Specifies the total maximum connections of the Apache HTTP client. The default value is 128.

Data type: Integer

scout.http.proxyPatterns

Configure proxies for the ConfigurableProxySelector. If a URI matches a pattern the corresponding proxy will be used.

By default no proxy is used.

The property value is of the format REGEXP_FOR_URI=PROXY_HOST:PROXY_PORT

Example:

scout.http.proxyPatterns[0]=.*\.example.com(:\d+)?=127.0.0.1:8888
scout.http.proxyPatterns[1]=.*\.example.org(:\d+)?=proxy.company.com

Data type: List

scout.http.redirectPost

Enable redirect of POST requests (includes non-idempotent requests). The default value is true

Data type: Boolean

scout.http.retryOnNoHttpResponseException

Enable retry of request (includes non-idempotent requests) on NoHttpResponseException

Assuming that the cause of the exception was most probably a stale socket channel on the server side.

The default value is true

Data type: Boolean

scout.http.retryOnSocketExceptionByConnectionReset

Enable retry of request (includes non-idempotent requests) on {@link SocketException} with message Connection reset

Assuming that the cause of the exception was most probably a stale socket channel on the server side.

The default value is true

Data type: Boolean

scout.http.transportFactory

Fully qualified class name of the HTTP transport factory the application uses. The class must implement org.eclipse.scout.rt.shared.http.IHttpTransportFactory.

By default org.eclipse.scout.rt.shared.http.ApacheHttpTransportFactory is used.

Data type: Fully qualified class name. The class must have org.eclipse.scout.rt.shared.http.IHttpTransportFactory in its super hierarchy.

scout.jandex.rebuild

Specifies if Jandex indexes should be rebuilt. Is only necessary to enable during development when the class files change often. The default value is false.

Data type: RebuildStrategy

scout.jaxws.consumer.connectTimeout

Connect timeout in milliseconds to abort a webservice request, if establishment of the connection takes longer than this timeout. A timeout of null means an infinite timeout. The default value is null.

Data type: Integer >= 0

scout.jaxws.consumer.portCache.corePoolSize

Number of ports to be preemptively cached to speed up webservice calls. The default value is 10.

Data type: Integer >= 0

scout.jaxws.consumer.portCache.enabled

Indicates whether to use a preemptive port cache for webservice clients.

Depending on the implementor used, cached ports may increase performance, because port creation is an expensive operation due to WSDL and schema validation.

The cache is based on a corePoolSize, meaning that that number of ports is created on a preemptive basis. If more ports than that number is required, they are created on demand and also added to the cache until expired, which is useful at a high load.

The default value is true.

Data type: Boolean

scout.jaxws.consumer.portCache.ttl

Maximum time in seconds to retain ports in the cache if the value of scout.jaxws.consumer.portCache.corePoolSize is exceeded. That typically occurs at high load, or if scout.jaxws.consumer.portCache.corePoolSize is undersized. The default value is 15 minutes.

Data type: Long >= 0

scout.jaxws.consumer.portPoolEnabled

To indicate whether to pool webservice clients.

Creating new service and Port instances is expensive due to WSDL and schema validation. Using the pool helps to reduce these costs. The default value is true.

The pool size is unlimited but its elements are removed after a certain time (configurable)

If this value is true, the value of property scout.jaxws.consumer.portCache.enabled has no effect.

Data type: Boolean

scout.jaxws.consumer.readTimeout

Read timeout in milliseconds to abort a webservice request, if it takes longer than this timeout for data to be available for read. A timeout of null means an infinite timeout. The default value is null.

Data type: Integer >= 0

scout.jaxws.implementor

Fully qualified class name of the JAX-WS implementor to use. The class must extend org.eclipse.scout.rt.server.jaxws.implementor.JaxWsImplementorSpecifics.

By default JAX-WS Metro (not bundled with JRE) is used. For that to work, add the Maven dependency to JAX-WS Metro to your server application`s pom.xml: com.sun.xml.ws:jaxws-rt:2.3.5.

Data type: Fully qualified class name. The class must have org.eclipse.scout.rt.server.jaxws.implementor.JaxWsImplementorSpecifics in its super hierarchy.

scout.jaxws.loghandlerDebug

Indicates whether to log SOAP messages in debug or info level. The default value is false.

Data type: Boolean

scout.jaxws.provider.authentication.basicRealm

Security Realm used for Basic Authentication; used by org.eclipse.scout.rt.server.jaxws.provider.auth.method.BasicAuthenticationMethod. The default value is JAX-WS.

Data type: String

scout.jaxws.provider.user.authenticator

Technical Subject used to authenticate webservice requests. The default value is jaxws-authenticator.

Data type: Subject name as String

scout.jaxws.provider.user.handler

Technical subject used to invoke JAX-WS handlers if the request is not authenticated yet; used by org.eclipse.scout.rt.server.jaxws.provider.handler.HandlerDelegate.

The default value is jaxws-handler.

Data type: Subject name as String

scout.jetty.port

The port under which the jetty will be running.

Data type: Integer between 1 and 65535

scout.jobmanager.allowCoreThreadTimeOut

Specifies whether threads of the core-pool should be terminated after being idle for longer than the value of property scout.jobmanager.keepAliveTime. The defautl value is false.

Data type: Boolean

scout.jobmanager.corePoolSize

The number of threads to keep in the pool, even if they are idle. The default value is 25.

Data type: Integer >= 0

scout.jobmanager.keepAliveTime

The time limit (in seconds) for which threads, which are created upon exceeding the scout.jobmanager.corePoolSize limit, may remain idle before being terminated. The default value is 1 minute.

Data type: Long >= 0

scout.jobmanager.maximumPoolSize

The maximal number of threads to be created once the value of scout.jobmanager.corePoolSize is exceeded. The default value is unlimited (which means limited by the resources of the machine).

Data type: Integer >= 0

scout.jobmanager.prestartCoreThreads

Specifies whether all threads of the core-pool should be started upon job manager startup, so that they are idle waiting for work.

By default this is disabled in development mode (property scout.devMode is true) and enabled otherwise.

Data type: Boolean

scout.loadWebResourcesFromFilesystem

Specifies if the application should look for web resources (like .js, .html or .css) on the local filesystem. If true, the resources will be searched in modules that follow the Scout naming conventions (e.g. name.ui.app.dev, name.ui.app, name.ui) on the local filesystem first and (if not found) on the classpath second. If false, the resources are searched on the Java classpath only. By default this property is true in dev mode and false otherwise.

Data type: Boolean

scout.mail.bouncedetector.heuristic.contents

Non-standard email bounce detection: content is checked against the provided list of heuristic contents (partial match, case-insensitive)

Data type: List

scout.mail.bouncedetector.heuristic.senderPrefixes

Non-standard email bounce detection: sender is checked against the provided list of heuristic sender prefixes (prefix match, case-insensitive)

Data type: List

scout.mail.bouncedetector.heuristic.subjects

Non-standard email bounce detection: subject is checked against the provided list of heuristic subjects (partial match, case-insensitive)

Data type: List

scout.malwareScanner.path

Path to a malware scanner checked directory. The default value is null which means the system temp path is used.

Data type: String

scout.mom.cluster.destination.clusterNotificationTopic

Name of the topic for cluster notifications published by scout application.

Data type: IDestination

scout.mom.cluster.environment

Contains the configuration to connect to the network or broker. This configuration is specific to the MOM implementor

Example to connect to a peer based cluster, which is useful in development mode because there is no central broker:

scout.mom.cluster.environment[scout.mom.name]=Scout Cluster MOM
scout.mom.cluster.environment[scout.mom.connectionfactory.name]=ClusterMom
scout.mom.cluster.environment[java.naming.factory.initial]=org.apache.activemq.jndi.ActiveMQInitialContextFactory
scout.mom.cluster.environment[java.naming.provider.url]=failover:(peer://mom/cluster?persistent=false)
scout.mom.cluster.environment[connectionFactoryNames]=ClusterMom

Data type: Map

scout.mom.cluster.implementor

Specifies the MOM implementor.

Example to work with a JMS based implementor:

scout.mom.cluster.implementor=org.eclipse.scout.rt.mom.jms.JmsMomImplementor

Data type: Fully qualified class name. The class must have org.eclipse.scout.rt.mom.api.IMomImplementor in its super hierarchy.

scout.mom.failover.connectionRetryCount

Specifies the connection retry count for connection failover. Default is 15. The value 0 disables connection failover.

Data type: Integer

scout.mom.failover.connectionRetryIntervalMillis

Specifies the connection retry interval in milliseconds. Default is 2000ms.

Data type: Integer

scout.mom.failover.sessionRetryIntervalMillis

Specifies the session retry interval in milliseconds. Default is 5000ms.

Data type: Integer

scout.mom.marshaller

Specifies the default Marshaller to use if no marshaller is specified for a MOM or a destination. By default the JsonDataObjectMarshaller is used.

Data type: Fully qualified class name. The class must have org.eclipse.scout.rt.mom.api.marshaller.IMarshaller in its super hierarchy.

scout.mom.requestreply.cancellationTopic

Specifies the default topic to receive cancellation request for request-reply communication. By default a defined topic with the name scout.mom.requestreply.cancellation is used.

Data type: IDestination

scout.mom.requestreply.enabled

Specifies if request-reply messaging is enabled by default. This value can also be configured individually per MOM. The default value is true.

Data type: Boolean

scout.nodeId

Specifies the cluster node name. If not specified a default id is computed.

Data type: String

scout.remotefileRootPath

Absolute path to the root directory of the RemoteFileService. The default value is null.

Data type: String

scout.serverSessionTtl

Server sessions that have not been accessed for the specified number of milliseconds are removed from the cache. The default value is one day.

Data type: Long >= 0

scout.servicetunnel.compress

Specifies if the service tunnel should compress the data. If null, the response decides which is default to true.

Data type: Boolean

scout.servicetunnel.maxConnectionsPerRoute

Specifies the default maximum connections per route property for the HTTP service tunnel.

Overrides the value from scout.http.maxConnectionsPerRoute for the service tunnel.

Default value is 2048.

Data type: Integer

scout.servicetunnel.maxConnectionsTotal

Specifies the default total maximum connections property for the HTTP service tunnel.

Overrides the value from scout.http.maxConnectionsTotal for the service tunnel.

The default value is 2048.

Data type: Integer

scout.servicetunnel.targetUrl

Specifies the URL to the ServiceTunnelServlet on the backend server.

By default this property points to the value of property scout.backendUrl with /process appended.

Data type: String

scout.smtp.connectionTimeout

Socket connection timeout value in milliseconds.

Data type: Integer >= 0

scout.smtp.debugReceiverEmail

If specified all emails are sent to this address instead of the real one. This may be useful during development to not send emails to real users by accident.

Data type: String

scout.smtp.pool.maxConnectionLifetime

Max. lifetime of pooled connections in seconds.

Data type: Integer >= 0

scout.smtp.pool.maxIdleTime

Max. idle time for pooled connections in seconds.

Data type: Integer >= 0

scout.smtp.pool.waitForConnectionTimeout

Max. wait time for SMTP connection in seconds. If the value is 0, callers will wait infinitely long for SMTP connections.

Data type: Integer >= 0

scout.smtp.readTimeout

Socket read timeout value in milliseconds.

Data type: Integer >= 0

scout.sql.directJdbcConnection

If true a direct JDBC connection is created. Otherwise, a JNDI connection is used. The default value is true.

Data type: Boolean

scout.sql.jdbc.driverName

The driver name to use. By default oracle.jdbc.OracleDriver is used.

Data type: String

scout.sql.jdbc.mappingName

The JDBC mapping name. By default jdbc:oracle:thin:@localhost:1521:ORCL is used.

Data type: String

scout.sql.jdbc.pool.connectionBusyTimeout

Connections will be closed after this timeout in milliseconds even if the connection is still busy. The default value is 6 hours.

Data type: Long >= 0

scout.sql.jdbc.pool.connectionIdleTimeout

Idle connections will be closed after this timeout in milliseconds. The default value is 5 minutes.

Data type: Long >= 0

scout.sql.jdbc.pool.size

The maximum number of connections to create. The default pool size is 25.

Data type: Integer >= 0

scout.sql.jdbc.properties

Semicolon separated list of properties to pass to the JDBC connection. The default value is null. E.g.: key1=val1;key2=val2

Data type: String

scout.sql.jdbc.statementCacheSize

Maximum number of cached SQL statements. The default value is 25.

Data type: Integer >= 0

scout.sql.jndi.initialContextFactory

The name of the object to lookup in the JNDI context. Default is null.

Data type: String

scout.sql.jndi.name

The name of the object to lookup in the JNDI context. Default is null.

Data type: String

scout.sql.jndi.providerUrl

JNDI provider url (e.g. ldap://somehost:389). Default is null.

Data type: String

scout.sql.jndi.urlPkgPrefixes

A colon-separated list of package prefixes for the class name of the factory class that will create a URL context factory. Default is null.

Data type: String

scout.sql.password

The password to connect to the database (JDBC or JNDI)

Data type: String

scout.sql.transactionMemberId

ID of the transaction member on which the connection is available.

Data type: String

scout.sql.username

The username to connect to the database (JDBC or JNDI)

Data type: String

scout.texts.showKeys

If this property is set to true, the TextKeyTextProviderService will be registered with high priority, and each call to TEXTS.get() will return the given text key instead of the translation.

This is useful for debug/testing purposes or exporting forms to JSON.

By default this property is false.

Data type: Boolean

scout.tiles.dataLoadQueueTimeoutSeconds

Maximum number of seconds a tile load job can execute until it is automatically cancelled. The default value is 2 minutes.

Data type: Integer >= 0

scout.tiles.maxConcurrentDataLoadThreads

Maximum number of threads per server that can be created to load tiles. The default value is 25.

Data type: Integer >= 0

scout.trustedCertificates

URIs to DER (Base64) encoded certificate files that should be trusted. The URI may refer to a local file or a resource on the classpath (use classpath: prefix). The default value is an empty list.

Data type: List

scout.ui.backgroundPollingMaxWaitTime

The polling request (which waits for a background job to complete) stays open until a background job has completed or the specified number of seconds elapsed.

This property must have a value between 3 and the value of property scout.ui.maxUserIdleTime.

By default this property is set to 1 minute.

Data type: Long >= 0

scout.ui.locales

Contains a comma separated list of supported locales (e.g. en,en-US,de-CH).

This is only relevant if locales.json and texts.json should be sent to the client, which is not the case for remote apps. So this property is only used for JS only apps.

By default no locales are supported.

Data type: List

scout.ui.maxUserIdleTime

If a user is inactive (no user action) for the specified number of seconds, the session is stopped and the user is logged out.

By default this property is set to 4 hours.

Data type: Long >= 0

scout.ui.modelJobTimeout

The maximal timeout in seconds to wait for model jobs to complete during a UI request. After that timeout the model jobs will be aborted so that the request may return to the client.

By default this property is set to 1 hour.

Data type: Long >= 0

scout.ui.sessionstore.housekeepingDelay

Number of seconds before the housekeeping job starts after a UI session has been unregistered from the store.

By default this property is set to 30 seconds.

Data type: Integer >= 0

scout.ui.theme

The name of the UI theme which is activated when the application starts.

Data type: String

scout.urlHints.enabled

Enable or disable changing UrlHints using URL parameters in the browser address line.

By default has the same value as the config property scout.devMode meaning it is by default only enabled in development mode.

Data type: Boolean

scout.util.defaultDecimalSupportProvider

Specifies the default DefaultDecimalSupportProvider to use. By default the DefaultDecimalSupportProvider is used.

Data type: Fully qualified class name. The class must have org.eclipse.scout.rt.platform.util.DECIMAL$DefaultDecimalSupportProvider in its super hierarchy.

1. https://github.com/wildfly/jandex

2. https://en.wikipedia.org/wiki/.properties