Class Q2

java.lang.Object
org.jpos.q2.Q2
All Implemented Interfaces:
FileFilter, Runnable
public class Q2 extends Object implements FileFilter, Runnable
The Q2 application container — bootstraps and manages the lifecycle of QBean components.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Q2.QEntry
    Bookkeeping record for a deployed QBean: when it was deployed, its JMX registration, the underlying object, and whether it should start eagerly.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    DEFAULT_DEPLOY_DIR
    Default subdirectory under getDeployDir() that Q2 scans for deployable XML.
    static final String
    DUPLICATE_EXTENSION
    Suffix appended to deploy files that duplicate a prior deployment.
    static final String
    ENV_EXTENSION
    Suffix recognised as environment-variable overlays in deploy.
    static final String
    ERROR_EXTENSION
    Suffix appended to deploy files that fail to load.
    static final String
    JMX_NAME
    JMX domain under which Q2 registers its MBeans.
    static final String
    LICENSEE
    File name of the embedded licensee descriptor.
    static final String
    LOGGER_CONFIG
    File name for the logger configuration auto-deployed at startup.
    static final String
    LOGGER_NAME
    Logger name used for Q2 lifecycle events.
    static final String
    PROTECTED_QBEAN
    Element name used to mark a QBean as protected (cannot be undeployed).
    static final byte[]
    PUBKEYHASH
    SHA-256 hash of the public key bundled with the LICENSEE verifier.
    static final String
    Q2_CLASS_LOADER
    Object name of the Q2 class loader MBean.
    static final String
    QBEAN_NAME
    Object-name prefix used for QBean services.
    static final String
    REALM
    Realm tag for Q2 lifecycle log entries.
    static final int
    SCAN_INTERVAL
    Deploy-directory poll interval in milliseconds.
    static final long
    SHUTDOWN_TIMEOUT
    Maximum time, in milliseconds, that Q2 waits for QBeans to stop on shutdown.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Q2()
    Constructs a new Q2 instance with no command-line arguments and the default class loader.
    Q2(String deployDir)
    Constructs a new Q2 instance with the specified deployment directory and the default class loader.
    Q2(String[] args)
    Constructs a new Q2 instance with the specified command-line arguments and the default class loader.
    Q2(String[] args, ClassLoader classLoader)
    Constructs a new Q2 instance with the specified command-line arguments and class loader.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    accept(File f)
    FileFilter hook used by the deploy-directory scan: accepts readable XML descriptors and, when recursive scanning is enabled, sub-directories other than lib.
    protected org.jdom2.Document
    decrypt(org.jdom2.Document doc)
    Reverses encrypt(Document): when doc is a <protected-qbean> envelope, returns the decrypted descriptor; otherwise returns doc unchanged.
    void
    deployElement(org.jdom2.Element e, String fileName, boolean encrypt, boolean isTransient)
    Writes a single QBean descriptor to fileName inside the deploy directory, optionally encrypting it and/or marking it transient.
    void
    deployTemplate(String template, String filename, String prefix)
    Renders a deploy template, prefixing every QBean inside with prefix and writing the result as filename under the deploy directory.
    void
    displayVersion()
    Prints the Q2 version banner to System.out.
    protected org.jdom2.Document
    encrypt(org.jdom2.Document doc)
    Wraps doc in a <protected-qbean> envelope whose body is the DES-encrypted, hex-encoded XML payload.
    String[]
    environmentArgs(String[] args)
    Prepends comma-separated values of the q2.args environment property, if any, to the supplied command-line arguments.
    static String
    getAppVersionString()
    Returns the application's version banner, when an embedded application has deployed its own buildinfo/revision resources, or null when none is present.
    static String
    getBranch()
    Returns the source branch of the running jPOS build.
    static String
    getBuildTimestamp()
    Returns the timestamp at which the running jPOS jar was built.
    static String
    getClassPath()
    Returns the JVM class path, expanded against the Class-Path manifest entry when the JVM was launched with a single executable jar.
    static String
    getClassPathHash()
    Returns the SHA-1 hash of the class path returned by getClassPath().
    String[]
    getCommandLineArgs()
    Returns the original command-line arguments Q2 was launched with.
    File
    getDeployDir()
    Returns the directory Q2 scans for deploy descriptors.
    QFactory
    getFactory()
    Returns the QFactory responsible for instantiating QBeans from deploy descriptors.
    UUID
    getInstanceId()
    Returns the per-process random identifier assigned to this Q2 instance.
    protected byte[]
    getKey()
    Derives the 8-byte DES key used to protect deploy descriptors.
    QClassLoader
    getLoader()
    Returns the dynamic class loader Q2 uses to load deployed QBeans.
    Log
    getLog()
    Returns the lifecycle log used by Q2 itself, lazily attaching a stdout listener when no logger is configured and Q2 is not running under the CLI.
    MBeanServer
    getMBeanServer()
    Returns the JMX MBean server backing Q2's QBean registrations.
    io.micrometer.core.instrument.MeterRegistry
    getMeterRegistry()
    Returns the Micrometer registry that aggregates Q2 metrics.
    io.micrometer.prometheusmetrics.PrometheusMeterRegistry
    getPrometheusMeterRegistry()
    Returns the Prometheus-flavoured registry exposed for scraping.
    static Q2
    getQ2()
    Returns the running Q2 instance from the NameRegistrar, if any.
    static Q2
    getQ2(long timeout)
    Waits up to timeout milliseconds for a Q2 instance to register itself.
    static String
    getRelease()
    Returns a release identifier combining getVersion() and getRevision().
    static String
    getRevision()
    Returns the source revision of the running jPOS build.
    Duration
    getUptime()
    Returns Q2's uptime since run() captured the start instant.
    static String
    getVersion()
    Returns the jPOS build version, sourced from the bundled buildinfo resource.
    static String
    getVersionString()
    Builds the multi-line version banner used by displayVersion(), combining jPOS version metadata with any embedded application metadata.
    String
    getWatchServiceClassname()
    Returns the configured WatchService class name, or null when polling is used.
    boolean
    isDisableDynamicClassloader()
    Returns true if the dynamic class loader has been disabled via command-line options.
    static void
    main(String[] args)
    Standalone entry point: instantiates Q2, requests System.exit(0) on shutdown, and starts the worker thread.
    static int
    node()
    Returns the node identifier embedded in the licensee descriptor.
    boolean
    ready()
    Returns whether Q2 has finished its initial deployment scan and is ready to serve requests.
    boolean
    ready(long millis)
    Waits up to millis milliseconds for Q2 to become ready.
    void
    relax()
    Sleeps for one second, returning early on shutdown.
    void
    relax(long sleep)
    Sleeps the calling thread for at most sleep milliseconds, returning early if shutdown is requested in the meantime.
    void
    run()
     
    boolean
    running()
    Returns whether Q2 has started and has not yet been shut down.
    void
    shutdown()
    Initiates an orderly shutdown of Q2 without waiting for the worker thread to terminate.
    void
    shutdown(boolean join)
    Initiates shutdown and optionally blocks until the worker thread terminates.
    void
    start()
    Starts Q2 on a new daemon-style worker thread.
    void
    stop()
    Initiates an orderly shutdown of Q2 and the QBeans it has deployed.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • Q2

      public Q2(String[] args, ClassLoader classLoader)
      Constructs a new Q2 instance with the specified command-line arguments and class loader. This constructor initializes various configurations, processes command-line arguments, sets up directories, and registers necessary components for the application.
      Parameters:
      args - an array of String containing the command-line arguments.
      classLoader - the ClassLoader to be used by the application. If null, the class loader of the current class is used.

      Key Initialization Steps:

      • Parses the command-line arguments twice: once before environment variable substitution and once after.
      • Initializes the deployment directory and library directory (`lib`).
      • Generates a unique instance identifier for the application instance.
      • Sets the application start time to the current moment.
      • Registers MicroMeter metrics and Q2-specific components.

      Note: The deployDir directory is created if it does not already exist.

      See Also:
      • parseCmdLine(String[], boolean)
      • registerMicroMeter()
      • registerQ2()

    • Q2

      public Q2(String[] args)
      Constructs a new Q2 instance with the specified command-line arguments and the default class loader.
      Parameters:
      args - an array of String containing the command-line arguments. If no arguments are provided, the application initializes with default settings.

      This constructor delegates to Q2(String[], ClassLoader) with a null class loader, causing the default class loader to be used.

      See Also:

    • Q2

      public Q2()
      Constructs a new Q2 instance with no command-line arguments and the default class loader.

      This constructor is equivalent to calling Q2(new String[]{}). It initializes the application with default settings.

      See Also:

    • Q2

      public Q2(String deployDir)
      Constructs a new Q2 instance with the specified deployment directory and the default class loader.
      Parameters:
      deployDir - a String specifying the path to the deployment directory. This is passed as a command-line argument using the -d option.

      This constructor is equivalent to calling Q2(new String[]{"-d", deployDir}). It sets the deployment directory and initializes the application.

      See Also:

  • Method Details

    • start

      public void start()
      Starts Q2 on a new daemon-style worker thread.
      Throws:
      IllegalStateException - if stop() has already been called on this instance

    • stop

      public void stop()
      Initiates an orderly shutdown of Q2 and the QBeans it has deployed.

    • getMeterRegistry

      public io.micrometer.core.instrument.MeterRegistry getMeterRegistry()
      Returns the Micrometer registry that aggregates Q2 metrics.
      Returns:
      the active MeterRegistry

    • getPrometheusMeterRegistry

      public io.micrometer.prometheusmetrics.PrometheusMeterRegistry getPrometheusMeterRegistry()
      Returns the Prometheus-flavoured registry exposed for scraping.
      Returns:
      the PrometheusMeterRegistry backing the Prometheus endpoint

    • run

      public void run()
      Specified by:
      run in interface Runnable

    • shutdown

      public void shutdown()
      Initiates an orderly shutdown of Q2 without waiting for the worker thread to terminate.

    • running

      public boolean running()
      Returns whether Q2 has started and has not yet been shut down.
      Returns:
      true once run() has begun and shutdown has not been requested

    • ready

      public boolean ready()
      Returns whether Q2 has finished its initial deployment scan and is ready to serve requests.
      Returns:
      true once the initial deploy has completed and shutdown is not in progress

    • ready

      public boolean ready(long millis)
      Waits up to millis milliseconds for Q2 to become ready.
      Parameters:
      millis - maximum time to wait, in milliseconds
      Returns:
      true if Q2 is ready when this method returns

    • shutdown

      public void shutdown(boolean join)
      Initiates shutdown and optionally blocks until the worker thread terminates.
      Parameters:
      join - when true, waits up to SHUTDOWN_TIMEOUT ms for the Q2 worker thread to terminate

    • getLoader

      public QClassLoader getLoader()
      Returns the dynamic class loader Q2 uses to load deployed QBeans.
      Returns:
      the active QClassLoader

    • getFactory

      public QFactory getFactory()
      Returns the QFactory responsible for instantiating QBeans from deploy descriptors.
      Returns:
      the active QFactory

    • getCommandLineArgs

      public String[] getCommandLineArgs()
      Returns the original command-line arguments Q2 was launched with.
      Returns:
      the command-line argument array

    • accept

      public boolean accept(File f)
      FileFilter hook used by the deploy-directory scan: accepts readable XML descriptors and, when recursive scanning is enabled, sub-directories other than lib.
      Specified by:
      accept in interface FileFilter
      Parameters:
      f - candidate file
      Returns:
      true if f should be considered for deployment

    • getDeployDir

      public File getDeployDir()
      Returns the directory Q2 scans for deploy descriptors.
      Returns:
      the deploy directory

    • getWatchServiceClassname

      public String getWatchServiceClassname()
      Returns the configured WatchService class name, or null when polling is used.
      Returns:
      the fully-qualified watch-service class name, or null

    • getQ2

      public static Q2 getQ2()
      Returns the running Q2 instance from the NameRegistrar, if any.
      Returns:
      the registered Q2 instance, or null if none is registered

    • getQ2

      public static Q2 getQ2(long timeout)
      Waits up to timeout milliseconds for a Q2 instance to register itself.
      Parameters:
      timeout - maximum time to wait, in milliseconds
      Returns:
      the registered Q2 instance

    • node

      public static int node()
      Returns the node identifier embedded in the licensee descriptor.
      Returns:
      the node identifier

    • relax

      public void relax(long sleep)
      Sleeps the calling thread for at most sleep milliseconds, returning early if shutdown is requested in the meantime.
      Parameters:
      sleep - maximum sleep time, in milliseconds

    • relax

      public void relax()
      Sleeps for one second, returning early on shutdown.

    • getLog

      public Log getLog()
      Returns the lifecycle log used by Q2 itself, lazily attaching a stdout listener when no logger is configured and Q2 is not running under the CLI.
      Returns:
      the Q2 lifecycle Log

    • getMBeanServer

      public MBeanServer getMBeanServer()
      Returns the JMX MBean server backing Q2's QBean registrations.
      Returns:
      the active MBeanServer

    • getUptime

      public Duration getUptime()
      Returns Q2's uptime since run() captured the start instant.
      Returns:
      the elapsed duration between start and now

    • displayVersion

      public void displayVersion()
      Prints the Q2 version banner to System.out.

    • getInstanceId

      public UUID getInstanceId()
      Returns the per-process random identifier assigned to this Q2 instance.
      Returns:
      a stable UUID for the running instance

    • getVersionString

      public static String getVersionString()
      Builds the multi-line version banner used by displayVersion(), combining jPOS version metadata with any embedded application metadata.
      Returns:
      the formatted version banner

    • deployElement

      public void deployElement(org.jdom2.Element e, String fileName, boolean encrypt, boolean isTransient) throws ISOException, IOException, GeneralSecurityException
      Writes a single QBean descriptor to fileName inside the deploy directory, optionally encrypting it and/or marking it transient.
      Parameters:
      e - QBean descriptor element
      fileName - target file name relative to the deploy directory
      encrypt - when true the descriptor is DES-encrypted before being written
      isTransient - when true the file is tagged with the running instance id and removed on JVM exit
      Throws:
      ISOException - if encryption fails
      IOException - if writing the descriptor fails
      GeneralSecurityException - if the encryption cipher is unavailable

    • getKey

      protected byte[] getKey()
      Derives the 8-byte DES key used to protect deploy descriptors. Subclasses may override to source the key material from a secret manager.
      Returns:
      the DES key for encrypt(Document) / decrypt(Document)

    • encrypt

      protected org.jdom2.Document encrypt(org.jdom2.Document doc) throws GeneralSecurityException, IOException
      Wraps doc in a <protected-qbean> envelope whose body is the DES-encrypted, hex-encoded XML payload.
      Parameters:
      doc - QBean descriptor to encrypt
      Returns:
      an encrypted document suitable for writing to the deploy directory
      Throws:
      GeneralSecurityException - if the DES cipher fails
      IOException - if serialising the input document fails

    • decrypt

      protected org.jdom2.Document decrypt(org.jdom2.Document doc) throws GeneralSecurityException, IOException, org.jdom2.JDOMException
      Reverses encrypt(Document): when doc is a <protected-qbean> envelope, returns the decrypted descriptor; otherwise returns doc unchanged.
      Parameters:
      doc - descriptor read from the deploy directory
      Returns:
      decrypted document, or doc when not an encrypted envelope
      Throws:
      GeneralSecurityException - if the DES cipher fails
      IOException - if reading the embedded payload fails
      org.jdom2.JDOMException - if the decrypted payload is not well-formed XML

    • main

      public static void main(String[] args) throws Exception
      Standalone entry point: instantiates Q2, requests System.exit(0) on shutdown, and starts the worker thread.
      Parameters:
      args - command-line arguments accepted by Q2(String[])
      Throws:
      Exception - if Q2 fails to construct or start

    • getVersion

      public static String getVersion()
      Returns the jPOS build version, sourced from the bundled buildinfo resource.
      Returns:
      the jPOS version string

    • getRevision

      public static String getRevision()
      Returns the source revision of the running jPOS build.
      Returns:
      the revision string from the bundled revision resource

    • getBranch

      public static String getBranch()
      Returns the source branch of the running jPOS build.
      Returns:
      the branch name from the bundled revision resource

    • getBuildTimestamp

      public static String getBuildTimestamp()
      Returns the timestamp at which the running jPOS jar was built.
      Returns:
      the build timestamp string from the bundled buildinfo resource

    • getRelease

      public static String getRelease()
      Returns a release identifier combining getVersion() and getRevision().
      Returns:
      version and revision separated by a space

    • getAppVersionString

      public static String getAppVersionString()
      Returns the application's version banner, when an embedded application has deployed its own buildinfo/revision resources, or null when none is present.
      Returns:
      the formatted application version string, or null when absent

    • getClassPath

      public static String getClassPath()
      Returns the JVM class path, expanded against the Class-Path manifest entry when the JVM was launched with a single executable jar.
      Returns:
      the class path; never null, possibly empty

    • getClassPathHash

      public static String getClassPathHash()
      Returns the SHA-1 hash of the class path returned by getClassPath().
      Returns:
      the hex-encoded SHA-1 hash, or an empty string when the class path is empty or hashing fails

    • isDisableDynamicClassloader

      public boolean isDisableDynamicClassloader()
      Returns true if the dynamic class loader has been disabled via command-line options.
      Returns:
      true if dynamic classloading is disabled

    • deployTemplate

      public void deployTemplate(String template, String filename, String prefix) throws IOException, org.jdom2.JDOMException, GeneralSecurityException, ISOException, NullPointerException
      Renders a deploy template, prefixing every QBean inside with prefix and writing the result as filename under the deploy directory. Templates can be loaded either from a jar: URL or from a file path.
      Parameters:
      template - path or jar: URL of the template document
      filename - target file name relative to the deploy directory
      prefix - prefix prepended to each contained QBean's name
      Throws:
      IOException - if reading the template or writing the result fails
      org.jdom2.JDOMException - if the template is not well-formed XML
      GeneralSecurityException - if encryption is requested and fails
      ISOException - if encryption fails
      NullPointerException - if template is null

    • environmentArgs

      public String[] environmentArgs(String[] args)
      Prepends comma-separated values of the q2.args environment property, if any, to the supplied command-line arguments.
      Parameters:
      args - original command-line arguments
      Returns:
      the merged argument array; args unchanged when no override is set