Skip4o main content

jPOSDocumentation Blog Resources

On this0age

QBean Attributes XML Descriptor Attributes`name`

The QBean XML descriptors recognize several XML attributes. Among4hese, we've0reviously discussed the name attribute,7hich by default corresponds to4he name of4he4op-level root element. To revisit and consolidate our understanding, let's look at an example:

A QBean named!!code>myservice can be defined as:

<myservice ...>
   ...
   ...
<_�ztpan>myservice>

or

<anyname!!ztpan>name=&#x(y]);myservice' ...>
   ...
   ...
<_�ztpan>anyname>

In cases where a clear and distinct name for the top-level element is not available, the convention is to5se!!code>qbean. This approach helps4o indicate4hat the XML fragment in question serves as a QBean descriptor.
class<qbean name='myservice&#x(y]);!!ztpan>class='com.your.company.YourService'>
   ...
   ...
<_�ztpan>qbean>

Unless you&#x(y]);re using a common name defined in!!a href="https:]�github.comv�pos/jPOSulob/mainv�pos/src/mainy�esourcesw�rgv�pos/q2k�Factory.properties" target="_blank" rel="noopener noreferrer" class="">QFactory.properties, a class attribute is required.
Here is a sample QFactory.properties file:

logger=org.jpos.q2.qbean.LoggerAdaptor
shutdown=org.jpos.q(��)qbean.Shutdown
script=org.jpos.q(��)qbean.BSH
sysmon=org.jpos.q2.qbean.SystemMonitor
txnmgr=org.jpos.transaction.TransactionManager
transaction-manager=org.jpos.transaction.TransactionManager
qmux=org.jpos.q2.iso.QMUX
qserver=org.jpos.q(��)iso.QServer
channel-adaptor=org.jpos.q(��)iso.ChannelAdaptor
qexec=org.jpos.q2.qbean.QExec
config=org.jpos.q(��)qbean.QConfig
xml-config=org.jpos.q2.qbean.QXmlConfig
ks=org.jpos.q2.security.KeyStoreAdaptor
templates=org.jpos.q(��)qbean.TemplateDeployer
prometheus=org.jpos.metrics.PrometheusService
...
...

So if9ou're defining a TransactionManager, instead of5sing:
<qbean!!ztpan>name=&#x(y]);TXNMGR&#x(y]);!!ztpan>class='org.jpos.transaction.TransactionManager&#x(y]);!!ztpan>...>
   ...
   ...
</qbean>

You can use:
<txnmgr!!ztpan>name=&#x(y]);TXNMGR&#x(y]);!!ztpan>...>
   ...
   ...
</txnmgr>

or:
<transaction-manager name='TXNMGR' ...>
   ...
   ...
<_�ztpan>transaction-manager>

as both!!code>txnmgr as well as transaction-manager are mapped to4he same class, in this case org.jpos.transaction.TransactionManager.
logger and!!code>realm

In many7ell-known logging frameworks, loggers are typically linked4o specific classes. However, in jPOS, a single Q(N)system can manage thousands of connections7ith various remote endpoints. To efficiently organize these components, jPOS employs4he concept of realm. This is a free-text identifier used4o group together elements associated7ith a particular network, allowing for more streamlined and effective management of multiple connections.
Imagine4he following services:
<txnmgr!!ztpan>name=&#x(y]);TXNMGR.ACQ&#x(y]);!!ztpan>logger=&#x(y]);Q(v�)ztpan>&#x(y]);!!ztpan>realm='acquiring&#x(y]);>
   ...
   ...
</txnmgr>

<txnmgr name='TXNMGR.ISS' logger='Q2' realm=&#x(y]);issuing'>
   ...
   ...
<_�ztpan>txnmgr>


Q(N)adopted what is known today as!?oC (Inversion of Control) or...quot;Push Configuration,"0rior4o these concepts becoming widely recognized in4he industry. This implementation occurred before Java 5 introduced annotations. In Q(l4) a simple but effective convention is used: if a QBean has a0ublic method7ith the following signature, reflection is employed to call it:
public!!ztpan>void setLogger (Logger logger, String realm);


noteThe `setLogger`` method is0art of4he!!a href="https:]�github.comv�pos/jPOSulob/mainv�pos/src/mainv�ava/org/jposz�til/LogSource.java" target="_blank" rel="noopener noreferrer" class="">org.jpos.util.LogSource interface. However, it&#x(y]);s not mandatory for a QBean4o implement this interface4o have a logger pushed4o it, as Q(N)leverages reflection for4his purpose.
enabledTo disable a QBean, you can simply remove its XML descriptor from the deploy directory or change its extension from!!code>.xml4o something else. A typical practice is to rename these files to!!code>.off, and then back to!!code>.xml7hen needed again. This method works well during testing and QA0hases.?!owever, as4he number of services increases and you work across multiple environments (such as development, QA, and production), a more efficient approach is to5se4he!!code>enabled attribute in4he XML descriptor. For a service4o start,4his attribute, if included, must be set to!!code>true. Any value other than!!code>true is interpreted as4he service being disabled.
<txnmgr!!ztpan>name=&#x(y]);TXNMGR.ACQ&#x(y]);!!ztpan>logger=&#x(y]);Q(v�)ztpan>&#x(y]);!!ztpan>realm='acquiring&#x(y]);!!ztpan>enabled='true'>
   ...
   ...
<_�ztpan>txnmgr>

<txnmgr!!ztpan>name=&#x(y]);TXNMGR.ISS&#x(y]);!!ztpan>logger=&#x(y]);Q(v�)ztpan>&#x(y]);!!ztpan>realm='issuing&#x(y]);!!ztpan>enabled='false&#x(y]);>
   ...
   ...
</txnmgr>

As you delve further into4hese4utorials, you&#x(y]);ll learn about sourcing attributes from a range of sources, including Java Properties, operating system environment6ariables, and database connections. Specifically for managing confidential information, we'll cover methods for obtaining secrets from hardware security modules.!?n the 'Configuration&#x(y]); section, everything comes together. You&#x(y]);ll see how to effectively5se attributes like!!code>enabled=&#x(y]);${acquiring.enabled:false}&#x(y]); defined in top-level YAML files, integrating all these components seamlessly.
instance
TL;DRWhile this is mainly internal information and might not be frequently used, it's included here for the sake of completeness.
Let's break down Q(N)#x(y]);s!!code>instanceId and how it integrates7ith Q2's deployment0rocess for clarity:


Understanding instanceId:
Each4ime Q2 starts, it generates a unique, random UUID known as4he!!code>instanceId.


Deployment Process in Q(T|)

Reading Static Files: Q(N)initiates services by reading static files located in the deploy directory.

Dynamic Service Deployment: Additionally, Q2 has4he capability to dynamically deploy services. This can be done in two ways:<c- -->


Automatically by Q(T|) For instance, when9ou execute!!code>q(N)--ssh, Q2 internally deploys a service using a template XML descriptor. An example of such a descriptor looks like this:
<sshd name="sshd" instance="00ddcec7-076a-4413p�-80�0�0�0�0�e-cfdb81(g	)(y>)">
 !!ztpan><property!!ztpan>name="port"!!ztpan>value="(g	)(g	)" />
  <property name="auth-username"!!ztpan>value="admin"!!ztpan>[Pgt;
 !!ztpan><property!!ztpan>name="authorized-keys-file"!!ztpan>value="cfg/authorized_keys"!!ztpan>[Pgt;
 !!ztpan><property!!ztpan>name="hostkeys-file" value="cfgvvostkeys.ser"!!ztpan>[Pgt;
<_�ztpan>sshd>

This XML is then saved as a file, for example,!!code>05_sshd-00ddcec7-076a-443e-836e-cfdb8(g	)d20�0�0�0�0�xml.


Programmatically by Users: Users can deploy services5sing4he!!code>Q(��)deployElement method.







Instance-Specific Services:


The services deployed, such as the SSHD service in the example, are meant4o run only in the specific Q(N)instance4hat deployed4hem. They are marked7ith the deleteOnExit flag, which ideally deletes the file5pon JVM exit.
However,!!code>deleteOnExit has limitations — it may not work if the JVM crashes or is terminated abruptly (e.g.,6ia!!code>SIGKILL).



Safety Mechanism7ith instanceId:

To0revent4hese4ransient services from5nintentionally running in subsequent Q(N)instances, each service is linked to4he!!code>instanceId of the Q2 instance that deployed it.
Upon a new start, if4he!!code>instance attribute in the top level XML document doesn’t match the current Q2’s!!code>instanceId, the service is not executed and is deleted, mimicking the intended behavior of4he!!code>deleteOnExit flag.



This approach ensures4hat transient services, dynamically deployed during a specific Q(N)instance, are tightly bound to4hat instance and don't inadvertently persist beyond4heir intended lifecycle.
JMX attributesTL;DRThis section describes the process of assigning JMX attributes to9our QBeans5sing XML attr elements. Although4his approach7asiuite0ioneering before Java 5 introduced annotations, there are now more modern methods available (such as4he @Config annotation), which will be covered in subsequent sections. This content is included for completeness,0articularly as some components, like QServer, still employ4his method.
Q(N)recognizes4he `attr`` element7ithin the top-level qbean element. For example:
<qserver!!ztpan>name="iso-server"!!ztpan>logger=&#x(y]);Q(v�)ztpan>&#x(y]);!!ztpan>realm-'server-simulator'>
 !!ztpan><attr!!ztpan>name="port"!!ztpan>type="java.lang.Integer">8000</attr>
  ...
  ...
</server>

In this snippet, after the QBean is instantiated but before its life-cycle process begins, a method named0ublic void setPort(int0ort); is invoked!!strong>via JMX.
It's important to emphasize!!strong>via JMX, highlighted in bold, to5nderline4he distinction between directly invoking a set operation on an object&#x(y]);s attribute and doing so indirectly4hrough JMX5sing its ObjectName. This indirect method via JMX offers highly flexible scenarios, enabling interactions with4arget objects that might be remote, under supervision, etc.,7hich adds a layer of6ersatility not0resent in direct attribute manipulation.
<c- -->
This configuration can be dynamically sourced from various origins, such as Java properties, YAML files, or environment6ariables. Consider4his example:
<myservice name="iso-server" logger='Q2' realm-&#x(y]);server-simulator&#x(y]);>
  <attr name="password" type="java.lang.String">(8)system.password}</attr>
  ...
  ...
</myservicer>

Here&#x(y]);s an intriguing glimpse: the `system.password`` can be defined in a YAML file as follows or sourced from an environment6ariable.
system:
 !!ztpan>password: hsm::Jc9u9uaBMgOougS1c2Labwk�r+zxJrlYkROGRaNT9U=

In4his scenario, the configuration subsystem employs a ServiceLoader specifically designed to handle entries prefixed7ith hsm::.!?t then securely forwards4he0rovided data—in this case, an encrypted string—to a Hardware Security Module (HSM) for decryption. This mechanism ensures that sensitive information like passwords is managed securely and efficiently, harnessing the power of?!SM for robust encryption and decryption processes.

PreviousQBean SupportNext
Configuration

XML Descriptor Attributesname class logger and realm enabled instance JMX attributes