This post is part of a series exploring the unique aspects and capabilities of WebSphere Liberty when running on z/OS.
We'll also explore considerations when moving from WebSphere traditional on z/OS to Liberty on z/OS.
To start at the beginning, follow this link to the first post.
---------------
Pop Quiz! Suppose you had this bit of configuration in your server.xml (and no other relevant stuff). What port would be used for the httpPort?
<variable name="myPort" value="9081"/>
<httpEndpoint id="defaultHttpEndpoint"
httpPort="${myPort}"
httpsPort="9443" />
<variable name="myPort" value="9082"/>
If you said ‘9081’ you would, like me, be wrong. The correct answer is ‘9082’. I was just sure that all the config was processed in the order it was found. However, it was pointed out to me (hat tip Jason and Avnindra) that it doesn’t work that way.
It would appear that whenever Liberty is processing its configuration and finds a variable it needs to resolve it goes to the list that is described here (at least it is at this link right now): https://openliberty.io/docs/latest/reference/config/server-configuration-overview.html#variable-substitution
As you can see, there are a whole bunch of places variables can get defined and Liberty hunts down the value it needs, and it looks at everything. So if you’ve got all your variables defined at the very end of your configuration, that’s ok. Liberty will find them. And in our case above the last-set value for “myPort” gets used.
Now at first I thought this wasn’t a big deal. Things are a little bit looser than I’d thought so you don’t have to define a variable before you use it. Goes against my instincts, but it won’t hurt you to define them before use either. Whatever.
But….I realized this also means that variable names have to be unique across the configuration. Suppose your server.xml includes datasource1.xml and datasource2.xml. Suppose each of those files includes its own, separate, XML file that defines variables used in the datasource definitions (call ‘em ds1vars.xml and ds2vars.xml). Well, if those are maintained by different people, they might both reasonably define a variable called “dbPort” and set it. If we include datasource1.xml first then (and here it matters which one goes first) it will refer to “dbPort”, but Liberty will search the whole config looking for the value and the last definition it finds will be in db2vars.xml which is the port for datasource 2. Well, that’s not good.
What to do? If you have another look at that link above you’ll find one of the places Liberty looks for variable definitions is files in the ‘variables’ directory. If you scroll down a little bit you can see how Liberty handles the contents of this directory.
One thing you can do is create subdirectories within ‘variables’ and the name of the directory becomes part of the variable name. So we could create directories called db1 and db2 and both of those directories could have a file called dbPort whose contents are the appropriate port number for each db. Then the datasource1 config XML could refer to ${db1/dbPort} and get the right one.
You can also have a .properties file in the variables directory that contains name/value pairs for variables. You could use this as a common place to put all the variables which could help avoid collisions (if everybody follows the rules). Liberty won’t process a .properties file that’s in a variables subdirectory.
Or you can make it more complicated by having a list of ‘variables’ directories (see the doc about setting VARIABLE_SOURCE_DIRS). That doesn’t really help with the name-collision problem, but it is yet another way Liberty allows you to make your life more complicated, um, that is, provides you the flexibility to set things up in a variety of ways…. “Let’s be careful out there..” (A Hill Street Blues reference for those of you old enough to remember that…)