File structure

Configuration is defined in YAML files (their location was discussed in previous chapters) and consists of the following sections:

  • 'SERVERS' - definitions of entry points used for communication with a microservice.
  • 'ENTRY_POINTS' - additional parameters of entry points associated witch logical servers defined in 'SERVERS' section
  • 'TRANSMISSION' - contains access list (microservice name, class and method) for remote method invocation through TRANSMISSION PORT (from administration tools).
  • 'PROPERTIES' - list of runtime parameters of a microservice.
  • 'APPLICATION' - list of parameters related to Spring Application context
  • 'INITIALIZING_LOGGER' - configuration of microservice logger (the initialization phase).
  • 'MEMORY_ERRORS' - configuration of Memory Process Keeper for a microservice
  • 'THREAD_POOLS' - custom thread pools definitions


Description

Section 'SERVERS'

The section contains subsections, which are definitions of each entry point. There are three subsections, each relates to particular entry point. The name of a subsection is the name of entry point. The set of parameters for each subsection is the same.

The appropriate part of the configuration file:

SERVERS:
  JLRMC: #JLupin Remote Method Calls Fast Protocol:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: true
    waitToShutdownThreadsOnStop: 60000
    backlog: 0
    receiveBufferSize: 0
    isReuseAddress: false
    threadPoolSize: 128
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 240000
    isStartOnMainServerInitialize: true
  TRANSMISSION:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: false
    waitToShutdownThreadsOnStop: 60000
    backlog: 0
    receiveBufferSize: 0
    isReuseAddress: false
    threadPoolSize: 8
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 3600000
    isStartOnMainServerInitialize: true
  QUEUE:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: true
    waitToShutdownThreadsOnStop: 60000
    backlog: 1024
    receiveBufferSize: 1024
    isReuseAddress: false
    threadPoolSize: 128
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 240000
    isStartOnMainServerInitialize: true
[...]

Description:

Parameter Description
readTimeout The maximum time in milliseconds that a socket is ready to handle traffic, after this timeout the another initialization is needed and a socket is unavailable for some time. If you interested in reading more about it, please refer to Oracle's official documentation. USE WITH CAUTION !
isWaitForFinishExecuteAllRequests Graceful shutdown switch. It determines whether the Main Server waits to complete all requests before it stops.
waitToShutdownThreadsOnStop Graceful shutdown timeout. The time in milliseconds that main server waits to complete all requests. After this timeout the Main Server will be terminated regardless the status of requests.
backlog The maximum queue length for incoming connections. If you interested in reading more about it, please refer to Oracle's official documentation. USE WITH CAUTION !
receiveBufferSize The value of this parameter is used both to set the size of the internal socket receive buffer, and to set the size of the TCP receive window that is advertised to the remote peer. If you interested in reading more about it, please refer to Oracle's official documentation. USE WITH CAUTION !
isReuseAddress Enabling this parameter prior to binding the socket allows the socket to be bound (through 'bind' method) even though a previous connection is in a timeout state. If you interested in reading more about it, please refer to Oracle's official documentation. USE WITH CAUTION !
threadPoolSize The number of threads that is assigned to process requests on the entry point
isLogPeriodicOnDebug The switch to ignore DEBUG log level for periodic tasks in JLupin Platform core components.
isDestroyThreadOnTimeout The switch that determines if microservice destroys thread after threadExecutingTimeOut occurs. USE WITH CAUTION !
threadExecutingTimeOut The maximum time of execution by a thread (from client perspective), expressed in milliseconds. After this period of time the socket associated with the request is closed, the thread executes request to the end.
isStartOnMainServerInitialize The switch that determines if the logical service is started during Main Server startup procedure.

Section 'ENTRY_POINTS'

This section contains the logical definitions of an interface (entry point) of a native microservice.

The appropriate part of the configuration file:

[...]
ENTRY_POINTS:
  QUEUE:
     threadAmount: 512
     howOftenCheckingServerInMillis: 5000
     repeatsAmount: 4
     timeToWaitBetweenRepeatProbeInMillis: 1000
[...]

Description:

Entry point type Parameter Description
QUEUE threadAmount The number of threads assigned to an entry point on which asynchronous requests are processed.
QUEUE howOftenCheckingServerInMillis The loop period (expressed in milliseconds) in which the queue delegator checks if there are results to be returned to output queue.
QUEUE repeatsAmount The number of attempts made by the delegator to deliver the results to the output queue (during each attempt, the delegator checks the entire environment available to him in order to find an available output queue).
QUEUE timeToWaitBetweenRepeatProbeInMillis The time period (expressed in milliseconds) at which the queue delegator waits between successive attempts to return results.

Section 'TRANSMISSION'

This section contains access list (microservice name, class and method) for remote method invocation through TRANSMISSION PORT (from administration tools).

The appropriate part of the configuration file:

[...]
TRANSMISSION:
  MICROSERVICES_GRANT_ACCESS:
    MICROSERVICES_LIST:
      #- microserviceName: 'sampleMicroservice'
      #  serviceName: 'sampleServiceName'
      #  methodName: 'sampleMethodName'
      #- microserviceName: 'sampleMicroservice2'
      #  serviceName: 'sampleServiceName2'
      #  methodName: 'sampleMethodName2'
[...]

Description:

Parameter Description
microserviceName The name of a microservice
serviceName The name of a class provided as a service
methodName The name of the method, included in serviceName

Section 'PROPERTIES'

The appropriate part of the configuration file:

[...]
PROPERTIES:
  #jvmOptions1: '-Xms128M -Xmx256M -agentlib:jdwp=transport=dt_socket,address=12998,server=y,suspend=n'
  jvmOptions1: '-Xms64M -Xmx128M' #jvmOptions_2 - default the same as jvmOptions_1
  #jvmOptions2: '-Xms128M -Xmx256M'
  externalPort: '8000'
  version: '1.5.0.0'
  switchDelayTime: 0
  connectionSocketTimeoutInMillis: 1000
  readTimeoutInMillis: 30000
  isKeepAlive: false
  isOOBInline: false
  isTcpNoDelay: false
  isReuseAddress: false
  sendBufferSize: 0
  receiveBufferSize: 0
  soLinger: 0
  trafficClass: 0
  #javaExecutablePath: 'c:\\jvm\\bin\\java.exe'
  #additionalClassPath: 'c:\\temp\\*'
  isStartOnMainServerInitialize: true
  priorityStartOnMainServerInitialize: 4
  waitForProcessInitResponseTimeInMillis: 90000
  waitForProcessStartResponseTimeInMillis: 90000
  waitForProcessDestroyResponseTimeInMillis: 30000
  isAllFilesToJVMAppClassLoader: false
  isArchiveOnStart: false
  startLogMode: INFO
  isInitErrorCauseWithNetworkInformation: true
  isJmxEnabled: true
  jmxOptions: '-Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false'
  jmxPrimaryPort: -1
  jmxSecondaryPort: -1
  checkAvailableScript: 'function isAvailable(checkResponseTimeInMillis, jrmcActiveThreads, jrmcMaxThreads,
                                              queueActiveThreads, queueMaxThreads, servletActiveThreads, servletMaxThreads,
                                              jvmMaxMemoryInBytes, jvmTotalMemoryInBytes, jvmFreeMemoryInBytes,
                                              jvmProcessCpuLoadInPercentage, userAvailableFlag) {

                          var isAvailableByUser = Boolean(userAvailableFlag);
                            if(checkResponseTimeInMillis > 20000 || !isAvailableByUser) {
                               return false;
                            }
                            return true;
                         }'
[...]

Description:

Parameter Description
jvmOptions1 The JVM options that is used when a microservice starts
jvmOptions2 The JVM options that is used after a microservice is restarted. The default value equals to jvmOptions1
externalPort This parameter is not used
version The version of a native microservice, this value is shown on various informational channels, such as JLupin Local Console, HTTP INFORMATION PORT, JMX etc. This parameter doesn't have any influence on the JLupin internal mechanisms.
switchDelayTime The time in milliseconds that Main Server waits after the new instance of microservice is started (in the process of microservice's restart) before the previous one is stopped. This is important parameter when health checking period of external balancer is taken into consideration.
connectionSocketTimeoutInMillis The maximum period of time in milliseconds for connection initialization from Main Server to microservice
readTimeoutInMillis The maximum period of time in milliseconds for handling request by microservice, sent by Main Server
expectedCheckResponseTimeInMillis The expected microservice response time in milliseconds in health checking process performed by Main Server
isKeepAlive It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
isOOBInline It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
isTcpNoDelay It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
isReuseAddress It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
sendBufferSize It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
receiveBufferSize It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
soLinger It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
trafficClass It's a generic parameter of a socket, created by JLupin Load Balancer (on Main Server) and used for connection to the microservice, If you would like to know more about this parameter, please refer to Oracle's official documentation. USE WITH CAUTION !
javaExecutablePath The path of JAVA binary that is used for starting the microservice. Usually this option is used when different JDK is needed for the microservice than for Main Server.
additionalClassPath Additional classpath that will be automatically added to startup command of the microservice.
isStartOnMainServerInitialize The switch that determines if the microservice should be started during Main Server startup procedure (start.cmd / start.sh).
priorityStartOnMainServerInitialize The priority for the microservice which determines the order of microservices startup during Main Server startup procedure (start.cmd / start.sh). The higher value of this parameter the later the microservice will be launched. This option gives opportunity to set the proper sequence of microservices startup where operational relations should be taken into account.
waitForProcessInitResponseTimeInMillis The time in milliseconds that Main Server waits for microservice's process initialization on the operating system level.
waitForProcessStartResponseTimeInMillis The parameter is no longer in use. It is present for backward compatibility.
waitForProcessDestroyResponseTimeInMillis The parameter is no longer in use. It is present for backward compatibility.
isAllFilesToJVMAppClassLoader An advanced setting referred to class loaders. You can try to change it only in case of ClassNotFoundException, where everything seems to be OK. In same cases external libraries use classloaders individually to load dependencies, and it turned out that sometimes they don't do it according to best practices. in such cases JVM should be set as a class loading coordinator.
isArchiveOnStart The switch determines if microservice's resources are archived in $JLUPIN_HOME/application_archive during start or restart of the microservice. This repository is for quick recovery the previous version of the microservice, for example if the new version of the microservice works incorrectly (application errors, wrong algorithms)
startLogMode The log severity of native microservice engine. The default value is 'INFO'.
isInitErrorCauseWithNetworkInformation In case of synchronous requests going through many microservices, this parameters determines if the microservice adds IP address to suppressed part of the stack, being prepared by the platform in case of exception occurs.
isJmxEnabled The switch that determines if JMX interface of a microservice is turned on (change needs restart)
jmxOptions The set of JMX parameters
jmxPrimaryPort The primary port a JMX interface (it's active after microservice startup), the value '-1' means automated port assignment performed by Main Server. The current JMX port can be taken from HTTP INFORMATION PORT, /getAllEnvironmentState.
jmxSecondaryPort The secondary port a JMX interface (it's active just after the first microservice restart), the value '-1' means automated port assignment performed by Main Server. The current JMX port can be taken from HTTP INFORMATION PORT, /getAllEnvironmentState.
checkAvailableScript The function written in Java Script, used by JLupin Load Balancer on Main Server to determine under what conditions this particular microservice should be set as unavailable.

Section 'APPLICATION'

The appropriate part of the configuration file:

[...]
APPLICATION:
  applicationContainerProducerClassName: 'com.example.currency.converter.configuration.CurrencyConverterChfJLupinConfiguration'
[...]

Description:

Parameter Description
applicationContainerProducerClassName The class that is responsible for providing the Spring Context to the JLupin Platform.

Section 'INITIALIZING_LOGGER'

The appropriate part of the configuration file:

[...]
INITIALIZING_LOGGER:
  #directoryPath: '/logs/server'
  #fileName: 'file_name'
  fileExtension: 'log'
  fileSizeInMB: 20
  maxFiles: 10
[...]

Description:

Parameter Description
directoryPath The alternative directory for microservice's logs. The default is $JLUPIN_HOME/logs.
fileName The prefix of microservice log file.
fileExtension The extension of microservice log file.
fileSizeInMB The maximum log file size, expressed in MB.
maxFiles The maximum number of files. If the limit is exceeded, the first file is used again.

Section 'MEMORY_ERRORS'

The appropriate part of the configuration file:

[...]
MEMORY_ERRORS:
  isRestartOnError: true
  howManyTimes: 4
  percentageGrowth: 15
  isHeapDump: true
[...]

Description:

Parameter Description
isRestartOnError Determines if the microservice is restarted in case of OutOfMemoryError or StackOverFlow occurs.
howManyTimes Number of restart iterations if the memory errors still occur.
percentageGrowth Specifies how many percent of the heap will be increased in case of the restart.
isHeapDump Determines if the heap dump is performed in case of OutOfMemoryError.

Section 'THREAD_POOLS'

This section contains definitions of additional thread pools which could be used in the microservice. Each subsection is a separate thread pool definition, the name of subsection is the name of thread pool.

The appropriate part of the configuration file:

[...]
THREAD_POOLS:
  THREAD_POOL_1:
    size: 8
    waitingTimeForTasksCompletionInMillis: 10000
Parameter Description
size The number of threads in the pool. If it equals 0, the pool is not initialized.
waitingTimeForTasksCompletionInMillis The period of time that Main Server waits for threads to be inactive in shutdown procedure.


Default configuration file

SERVERS:
  JLRMC: #JLupin Remote Method Calls Fast Protocol:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: true
    waitToShutdownThreadsOnStop: 60000
    backlog: 0
    receiveBufferSize: 0
    isReuseAddress: false
    threadPoolSize: 128
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 240000
    isStartOnMainServerInitialize: true
  TRANSMISSION:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: false
    waitToShutdownThreadsOnStop: 60000
    backlog: 0
    receiveBufferSize: 0
    isReuseAddress: false
    threadPoolSize: 8
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 3600000
    isStartOnMainServerInitialize: true
  QUEUE:
    readTimeout: 480000
    isWaitForFinishExecuteAllRequests: true
    waitToShutdownThreadsOnStop: 60000
    backlog: 1024
    receiveBufferSize: 1024
    isReuseAddress: false
    threadPoolSize: 128
    isLogPeriodicOnDebug: true
    isDestroyThreadOnTimeout: false
    threadExecutingTimeOut: 240000
    isStartOnMainServerInitialize: true
ENTRY_POINTS:
  QUEUE:
    threadAmount: 512
    howOftenCheckingServerInMillis: 5000
    repeatsAmount: 4
    timeToWaitBetweenRepeatProbeInMillis: 1000
TRANSMISSION:
  MICROSERVICES_GRANT_ACCESS:
    MICROSERVICES_LIST:
      #- microserviceName: 'sampleMicroservice'
      #  serviceName: 'sampleServiceName'
      #  methodName: 'sampleMethodName'
      #- microserviceName: 'sampleMicroservice2'
      #  serviceName: 'sampleServiceName2'
      #  methodName: 'sampleMethodName2'
PROPERTIES:
  #jvmOptions1: '-Xms128M -Xmx256M -agentlib:jdwp=transport=dt_socket,address=12998,server=y,suspend=n'
  jvmOptions1: '-Xms64M -Xmx128M' #jvmOptions_2 - default the same as jvmOptions_1
  #jvmOptions2: '-Xms128M -Xmx256M'
  externalPort: '8000'
  version: '1.5.0.0'
  switchDelayTime: 0
  connectionSocketTimeoutInMillis: 1000
  readTimeoutInMillis: 30000
  isKeepAlive: false
  isOOBInline: false
  isTcpNoDelay: false
  isReuseAddress: false
  sendBufferSize: 0
  receiveBufferSize: 0
  soLinger: 0
  trafficClass: 0
  #javaExecutablePath: 'c:\\jvm\\bin\\java.exe'
  #additionalClassPath: 'c:\\temp\\*'
  isStartOnMainServerInitialize: true
  priorityStartOnMainServerInitialize: 4
  waitForProcessInitResponseTimeInMillis: 90000
  waitForProcessStartResponseTimeInMillis: 90000
  waitForProcessDestroyResponseTimeInMillis: 30000
  isAllFilesToJVMAppClassLoader: false
  isArchiveOnStart: false
  startLogMode: INFO
  isInitErrorCauseWithNetworkInformation: true
  isJmxEnabled: true
  jmxOptions: '-Dcom.sun.management.jmxremote.local.only=false -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false'
  jmxPrimaryPort: -1
  jmxSecondaryPort: -1
  checkAvailableScript: 'function isAvailable(checkResponseTimeInMillis, jrmcActiveThreads, jrmcMaxThreads,
                                              queueActiveThreads, queueMaxThreads, servletActiveThreads, servletMaxThreads,
                                              jvmMaxMemoryInBytes, jvmTotalMemoryInBytes, jvmFreeMemoryInBytes,
                                              jvmProcessCpuLoadInPercentage, userAvailableFlag) {

                          var isAvailableByUser = Boolean(userAvailableFlag);
                            if(checkResponseTimeInMillis > 20000 || !isAvailableByUser) {
                               return false;
                            }
                            return true;
                         }'
APPLICATION:
  applicationContainerProducerClassName: 'com.example.currency.converter.configuration.CurrencyConverterEurJLupinConfiguration'
INITIALIZING_LOGGER:
  #directoryPath: '/logs/server'
  #fileName: 'file_name'
  fileExtension: 'log'
  fileSizeInMB: 20
  maxFiles: 10
MEMORY_ERRORS:
  isRestartOnError: true
  howManyTimes: 4
  percentageGrowth: 15
  isHeapDump: true
THREAD_POOLS:
  THREAD_POOL_1:
    size: 8
    waitingTimeForTasksCompletionInMillis: 10000
  #THREAD_POOL_2:
  #  size: 8
  #  waitingTimeForTasksCompletionInMillis: 10000