|
| 1 | +--- |
| 2 | +title: "Variable injectors" |
| 3 | +date: 2019-02-23T17:19:24-05:00 |
| 4 | +draft: false |
| 5 | +weight: 10 |
| 6 | +--- |
| 7 | + |
| 8 | + |
| 9 | +Variable injectors are used to tokenize a model by substituting variable keys in place of attribute values, and creating a separate property file containing the variable values. This facilitates using the same domain model to create new domains in different environments. WebLogic Deploy Tooling includes several built-in injector directive files that can be used as-is or with modifications, and allows for creation of custom injector files. |
| 10 | + |
| 11 | +Variable injectors are used by the [Discover Domain Tool]({{< relref "/userguide/tools/discover.md" >}}), the [Prepare Model Tool]({{< relref "/userguide/tools/prepare.md" >}}), and the standalone [Variable Injector Tool]({{< relref "/userguide/tools/variable_injection.md" >}}) to tokenize the models they produce. |
| 12 | + |
| 13 | +{{% notice note %}} Variable injection on an attribute is only performed once. After being tokenized, an attribute is not re-tokenized by any subsequent injector directives. |
| 14 | +{{% /notice %}} |
| 15 | + |
| 16 | +#### Default configuration |
| 17 | + |
| 18 | +The default injector configuration is used by the standalone Variable Injector Tool, and by the Discover Domain Tool when it is run without the `-target` option. To enable variable injection for these tools, create a variable injector configuration by placing a JSON file named `model_variable_injector.json` into the `<WLSDEPLOY>/lib` directory. |
| 19 | + |
| 20 | +Another option is to configure variable injection in a [Custom configuration]({{< relref "/userguide/tools-config/custom_config.md" >}}) directory. Create the `model_variable_injector.json` file in the `$WDT_CUSTOM_CONFIG` directory. |
| 21 | + |
| 22 | +The variable injector configuration file contains a list of injector names that map to the names of the injector files to be applied to the model. |
| 23 | + |
| 24 | +Here is an example of a `model_variable_injector.json` file that will apply `topology` and `custom` injectors to the model. |
| 25 | + |
| 26 | +```json |
| 27 | +{ |
| 28 | + "injectors": [ |
| 29 | + "topology", |
| 30 | + "custom" |
| 31 | + ] |
| 32 | +} |
| 33 | +``` |
| 34 | + |
| 35 | +Each injector name in the list refers to an [injector directive file](#injector-directive-files), and they are applied to the attributes in the model in the specified order. |
| 36 | + |
| 37 | +A sample of a `model_variable_injector.json` file is included in the `WLSDEPLOY/samples` directory. |
| 38 | + |
| 39 | +#### Targeted configuration |
| 40 | + |
| 41 | +Targeted injector configuration is used by the Prepare Model Tool, and by the Discover Domain Tool when it is run with the `-target` option. In this case, the list of injector names to be applied is specified in the `variable_injectors` field of the `$WLSDEPLOY_HOME/lib/targets/<target-name>/target.json` configuration file. For example, the `$WLSDEPLOY_HOME/lib/targets/wko/target.json` file contains this value: |
| 42 | + |
| 43 | +```json |
| 44 | +{ |
| 45 | + ... |
| 46 | + "variable_injectors" : ["port", "host", "url"], |
| 47 | + ... |
| 48 | +} |
| 49 | +``` |
| 50 | + |
| 51 | +Each injector name in the list refers to an [injector directive file](#injector-directive-files), and they are applied to the attributes in the model in the specified order. |
| 52 | + |
| 53 | +For more information on creating and extending target configurations, see [Target environments]({{< relref "/userguide/target_env.md" >}}). |
| 54 | + |
| 55 | +#### Injector directive files |
| 56 | + |
| 57 | +Injector directive files contain a list of qualified attribute paths and associated directives. When a matching attribute is found in the model, the associated directive is applied to that attribute, then a property token with a unique variable name is injected into the model and replaces the attribute value. The variable name and model attribute value are placed into the external variable properties file. |
| 58 | + |
| 59 | +Injector directive files are placed in the `$WLSDEPLOY_HOME/lib/injectors` directory. User-defined files can be placed there or in a [Custom configuration]({{< relref "/userguide/tools-config/custom_config.md" >}}) directory. To use the custom configuration directory, place these files in `$WDT_CUSTOM_CONFIG/lib/injectors`. |
| 60 | + |
| 61 | +WebLogic Deploy Tool includes these pre-configured injector directive files: |
| 62 | + |
| 63 | +- `host.json` - All MBean host attribute values in the model are injected with a variable. |
| 64 | +- `port.json` - All MBean port attribute values in the model are injected with a variable. |
| 65 | +- `target.json` - All MBean target attribute values in the model are injected with a variable. |
| 66 | +- `topology.json` - Common environmental MBean attributes found in the topology section of the model are injected with a variable. This includes server, machine and Node Manager ports, listen addresses, and cluster messaging modes, addresses and ports. |
| 67 | +- `url.json` - All MBean URL attribute values in the model are injected with a variable. |
| 68 | + |
| 69 | +The following is a model snippet that shows injected variables after applying the `port` injector directive file. |
| 70 | + |
| 71 | +```yaml |
| 72 | + |
| 73 | +topology: |
| 74 | + Name: soa_domain |
| 75 | + AdminServerName: AdminServer |
| 76 | + Cluster: |
| 77 | + soa_cluster: |
| 78 | + osb_cluster: |
| 79 | + Server: |
| 80 | + AdminServer: |
| 81 | + ListenAddress: myadmin.example.com |
| 82 | + ListenPort: @@PROP:Server.AdminServer.ListenPort@@ |
| 83 | + Machine: machine1 |
| 84 | + SSL: |
| 85 | + Enabled: true |
| 86 | + ListenPort: @@PROP:Server.SSL.AdminServer.ListenPort@@ |
| 87 | + soa_server1: |
| 88 | + ListenAddress: managed1.example.com |
| 89 | + ListenPort: @@PROP:Server.soa_server1.ListenPort@@ |
| 90 | + Cluster: soa_cluster |
| 91 | + Machine: machine2 |
| 92 | + SSL: |
| 93 | + Enabled: true |
| 94 | + ListenPort: @@PROP:Server.SSL.soa_server1.ListenPort@@ |
| 95 | + soa_server2: |
| 96 | + ListenAddress: managed2.example.com |
| 97 | + ListenPort: @@PROP:Server.soa_server2.ListenPort@@ |
| 98 | + Cluster: soa_cluster |
| 99 | + Machine: machine3 |
| 100 | + SSL: |
| 101 | + Enabled: true |
| 102 | + ListenPort: @@PROP:Server.SSL.soa_server2.ListenPort@@ |
| 103 | +``` |
| 104 | +
|
| 105 | +And the resulting variable property file: |
| 106 | +
|
| 107 | +``` |
| 108 | +Server.AdminServer.ListenPort=7001 |
| 109 | +Server.AdminServer.SSL.ListenPort=7002 |
| 110 | +Server.soa_server1.ListenPort=8001 |
| 111 | +Server.soa_server1.SSL.ListenPort=8002 |
| 112 | +Server.soa_server2.ListenPort=8001 |
| 113 | +Server.soa_server2.SSL.ListenPort=8002 |
| 114 | +``` |
| 115 | + |
| 116 | +#### Custom variable injector |
| 117 | + |
| 118 | +To use custom injector directives, create an injector directive file with a meaningful name, and place it in the `$WLSDEPLOY_HOME/lib/injectors` directory, or `$WDT_CUSTOM_CONFIG/lib/injectors` if using a custom configuration directory. Add the file prefix to the list in the `model_variable_injector.json` file, or in the `target.json` file if targeted configuration is used. For example, create the file `custom.json`, and add a `custom` entry to the list. |
| 119 | + |
| 120 | +An injector directive contains a key that identifies an attribute to be tokenized, and an optional set of directive properties. The key is a period-separated MBean hierarchy and attribute name as they are defined in the model. Always exclude the name of the model section from the injector key. |
| 121 | + |
| 122 | +For example, an injector directive for the Server SSL Listen Port is as follows. This directive contains no additional properties. |
| 123 | + |
| 124 | +```json |
| 125 | +{ |
| 126 | + "Server.SSL.ListenPort": {} |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +**NOTE**: The hierarchy of MBeans in the model for the `ListenPort` attribute. Note that the MBean name of `AdminServer` is NOT included in the directive: |
| 131 | + |
| 132 | +```yaml |
| 133 | +topology: |
| 134 | + Server: |
| 135 | + AdminServer: |
| 136 | + ListenAddress: myadmin.example.com |
| 137 | + ListenPort: 7001 |
| 138 | + Machine: machine1 |
| 139 | + SSL: |
| 140 | + Enabled: true |
| 141 | + ListenPort: 7002 |
| 142 | +``` |
| 143 | +
|
| 144 | +A sample of a custom injector directive file is included in the `$WLSDEPLOY_HOME/samples/injectors` directory. |
| 145 | + |
| 146 | +#### Injector directive properties |
| 147 | + |
| 148 | +Include the following properties to refine the directive as specified. |
| 149 | + |
| 150 | +- `force:<attribute>` |
| 151 | + If the MBean hierarchy exists in the model, but the attribute does not, then the attribute will be added and persisted to the resulting model. The value stored in the |
| 152 | + model is the WebLogic default value. |
| 153 | + |
| 154 | +- `variable_value`: |
| 155 | + Replace the model value with the specified value in the variable properties. This may be used in conjunction with the force directive, replacing the default value with the indicated value. |
| 156 | + |
| 157 | +- `regexp`: |
| 158 | + A list of `regexp` patterns that will be applied to either the string values or map values of an attribute in the model. If the pattern matches, then the matching part of the |
| 159 | + string or dictionary will be injected with a property token and a unique variable name. |
| 160 | + |
| 161 | + - `pattern`: |
| 162 | + The regular expression pattern to apply to the string value or map values of an attribute. |
| 163 | + |
| 164 | + - `suffix`: |
| 165 | + The suffix name to append to each resulting variable name in order to create a unique variable name. |
| 166 | + |
| 167 | +The `regexp` list is useful when only a segment of a string value or map needs to be tokenized (giving you a clean list of property values in the variable properties file). You can inject more than one token into a string or map with multiple patterns. However, when you have more than one pattern, you must provide a suffix for each. This allows the tool to generate a unique variable name for each token in the string or map. |
| 168 | + |
| 169 | +The following is an example of how to effectively use the `regexp` directive list to search for a segment in a string value. In this example, we want to search for the host and port in each Oracle JDBC URL that uses the special Oracle URL notation, and create an entry for the host and port in the variable properties file. |
| 170 | + |
| 171 | +In the model, we expect to find a URL like the following: |
| 172 | + |
| 173 | +```yaml |
| 174 | + JDBCSystemResource: |
| 175 | + Database1: |
| 176 | + JdbcResource: |
| 177 | + JDBCDriverParams: |
| 178 | + URL: 'jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=slc05til.us.oracle.com)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orcl.us.oracle.com)))' |
| 179 | +``` |
| 180 | + |
| 181 | +We create a directive in our custom injector JSON file: |
| 182 | + |
| 183 | +```json |
| 184 | + "JDBCSystemResource.JdbcResource.JDBCDriverParams.URL": |
| 185 | + { |
| 186 | + "regexp": [ |
| 187 | + { |
| 188 | + "pattern": "(?<=PORT=)[\\w.-]+(?=\\))", |
| 189 | + "suffix": "Port" |
| 190 | + }, |
| 191 | + { |
| 192 | + "pattern": "(?<=HOST=)[\\w.-]+(?=\\))", |
| 193 | + "suffix": "Host" |
| 194 | + } |
| 195 | + ] |
| 196 | + }, |
| 197 | +``` |
| 198 | + |
| 199 | +When the tool is run, the pattern is applied to the URL string and tokens injected into the string: |
| 200 | + |
| 201 | +```properties |
| 202 | +URL: 'jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=@@PROP:JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Host@@:)(PORT=@@PROP:JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Port@@)))(CONNECT_DATA=(SERVICE_NAME=orcl.us.oracle.com)))' |
| 203 | +``` |
| 204 | + |
| 205 | +And the variables put in the properties file: |
| 206 | + |
| 207 | +```properties |
| 208 | +JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Host=slc05til.us.oracle.com |
| 209 | +JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Port=1521 |
| 210 | +``` |
| 211 | + |
| 212 | +#### Selecting specific MBean names for variable injection |
| 213 | + |
| 214 | +This final custom directive allows you to explicitly define which named entries for an MBean in the model you want to inject properties. For instance, you might want to tokenize an attribute just for a specific server. To define a list of one or more names for a specific MBean in the injector directive hierarchy, format the list as follows: |
| 215 | + |
| 216 | +``` |
| 217 | +MBean[comma separated list of names] |
| 218 | +``` |
| 219 | + |
| 220 | +To select only the Administration Server named `AdminServer` for a Server directive, use the format `Server[AdminServer]`. To select servers `soa_server1` and `soa_server2`, format the key as `Server[soa_server1,soa_server2]`. |
| 221 | + |
| 222 | +The injector tool recognizes two KEYWORDS for a user list, `MANAGED_SERVERS` (all the Managed Servers in the model) and `ADMIN_SERVER` (the Administration Server in the model). |
| 223 | + |
| 224 | +A custom injector for the Administration Server SSL listen port is: |
| 225 | + |
| 226 | +```json |
| 227 | +{ |
| 228 | + "Server[ADMIN_SERVER].SSL.ListenPort": {} |
| 229 | +} |
| 230 | +``` |
0 commit comments