Skip to content

Commit f39b50f

Browse files
CarolynRountreeCarolynRountree
committed
Add variable injector to the readme file
1 parent 6385f68 commit f39b50f

File tree

1 file changed

+214
-0
lines changed

1 file changed

+214
-0
lines changed

‎README.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -845,6 +845,220 @@ When creating the archive, the tool will try to gather all binaries, scripts, an
845845
1. Any binaries referenced from the `ORACLE_HOME` will not be gathered, as they are assumed to exist in any target domain to which model-driven operations will be applied. Doing this is key to allowing the model to be WebLogic Server version independent.
846846
2. In its current form, the discover domain Tool will only gather binaries and scripts that are accessible from the local machine. Warnings will be generated for any binaries or scripts that cannot be found but the configuration for those binaries will still be collected, where possible. It is the user's responsibility to add those missing files to the archive in the appropriate locations and edit the the model, as needed, to point to those files inside the archive using the relative path inside the archive (for example, `wlsdeploy/applications/myapp.ear`).
847847

848+
-----------------------------------------------
849+
Variable Injector Tool
850+
-----------------------------------------------
851+
852+
An optional feature for the Discover Domain is the Variable Injector tool. The variable injector will replace a selected model attribute value with a property marker containing a unique variable name. This variable name and the replaced value are inserted into a variable property file.
853+
854+
To enable the Variable Injector during the Discover Domain, you must place a json file named model_variable_injector.json into the <WLSDEPLOY>/lib directory. This file must be manually created and contain one of the pre-defined keywords and/or a CUSTOM designated file.
855+
856+
A variable name substitution is only performed once for an attribute during the variable injector run. The first substitution is not replaced by and subsequent matches.
857+
858+
The supported keywords are as follows:
859+
860+
- CREDENTIALS
861+
All MBean credentials attribute values (user and password) are injected with a variable property string and the string and value placed in the variable property file
862+
863+
- HOST
864+
All MBean Host attribute values in the model are injected with a variable property string and the string and value placed in the variable property file
865+
866+
- PORT
867+
All MBean Port attribute values in the model are injected with a variable property string and the string and value placed in the variable property file
868+
869+
- TARGET
870+
All MBean Target attribute values in the model are injected with a variable property string and the string and value placed in the variable property file
871+
872+
- TOPOLOGY
873+
Special MBean attributes found in the topology section of the model are injected with a variable property string and the string value placed in the variable
874+
property file. This includes server, machine and node manager ports, credentials and listen addresses, and cluster messaging modes, addresses and ports.
875+
876+
- URL
877+
All MBean URL attribute values in the model are injected with a variable property string and the string and value placed in the variable property file
878+
879+
These special keywords are defined in a keyword file that is installed into the <WLSDEPLOY>/lib directory. Each keyword is associated with an injector json file.
880+
Each injector json file is installed into the <WLSDEPLOY>/lib/injectors directory. An injector file contains the directives for the Variable Injector tool to
881+
inject variables into specific model attributes.
882+
883+
Here is an example of a model_variable_injector.json file using the PORT keyword.
884+
885+
```json
886+
{
887+
"PORT": {},
888+
}
889+
```
890+
891+
Below is a model snippet that shows injected variables for the port values in a topology section.
892+
893+
```$yaml
894+
895+
topology:
896+
Name: soa_domain
897+
AdminServerName: AdminServer
898+
Cluster:
899+
soa_cluster:
900+
osb_cluster:
901+
Server:
902+
AdminServer:
903+
ListenAddress: myadmin.example.com
904+
ListenPort: @@PROP:Server.AdminServer.ListenPort@@
905+
Machine: machine1
906+
SSL:
907+
Enabled: true
908+
ListenPort: @@PROP:Server.SSL.AdminServer.ListenPort@@
909+
soa_server1:
910+
ListenAddress: managed1.example.com
911+
ListenPort: @@PROP:Server.soa_server1.ListenPort@@
912+
Cluster: soa_cluster
913+
Machine: machine2
914+
SSL:
915+
Enabled: true
916+
ListenPort: @@PROP:Server.SSL.soa_server1.ListenPort@@
917+
soa_server2:
918+
ListenAddress: managed2.example.com
919+
ListenPort: @@PROP:Server.so_server2.ListenPort@@
920+
Cluster: soa_cluster
921+
Machine: machine3
922+
SSL:
923+
Enabled: true
924+
ListenPort: @@PROP:Server.SSL.soa_server2.ListenPort@@
925+
926+
And the resulting variable property file:
927+
928+
```txt
929+
Server.AdminServer.ListenPort=7001
930+
Server.AdminServer.SSL.ListenPort=7002
931+
Server.soa_server1.ListenPort=8001
932+
Server.soa_server1.SSL.ListenPort=8002
933+
Server.soa_server2.ListenPort=8001
934+
Server.soa_server2.SSL.ListenPort=8002
935+
```
936+
937+
To designate the name and location of the variable properties file, include the variable_file_name directive in the model_variable_injector.json file.
938+
939+
```json
940+
{
941+
"variable_file_name": "/home/savedomain/variables.properties",
942+
}
943+
```
944+
945+
If this directive is not included in the json file, the model or archive file name and location is used to create the variable properties file name and location. If the model_file command line
946+
argument is used on the Discover Domain run, the properties file name and location will be the same as the model file, with the file extension `.properties`. If only the archive file argument is present, the archive file name
947+
and location will be used to create the variable properties file name and location.
948+
949+
As with the archive and model file, each run of the discover domain tool will overwrite the contents of an existing variable property file with the values from the current run.
950+
951+
# Custom Variable Injector
952+
953+
You may customize the injector attribute replacement by using the CUSTOM keyword in the model_variable_injector.json. The CUSTOM keyword identifies a list of one or more custom injector json files.
954+
These injector json files will be processed first, in list order, and the resulting variable properties will not be replaced when processing additional keywords in the model variable injector json file.
955+
956+
An entry in the injector json file is a key that specifies the unique MBean attribute that will be injected, and an optional set of directives.
957+
958+
The injector is a period separated MBean hierarchy and attribute name as they are defined in the model. Do not enter the name of the model section into the injector key.
959+
960+
For example, an injector key for the Server SSL Listen Port is Server.SSL.ListenPort. The Server.SSL identifies the hierarchy in the model to the attribute.
961+
962+
```json
963+
{
964+
"Server.SSL.ListenPort": {},
965+
}
966+
```
967+
968+
An example of that hierarchy in a model (notice that the MBean name of AdminServer is NOT included):
969+
```yaml
970+
topology:
971+
Server:
972+
AdminServer:
973+
ListenAddress: myadmin.example.com
974+
ListenPort: 7001
975+
Machine: machine1
976+
SSL:
977+
Enabled: true
978+
ListenPort: 7002
979+
```
980+
981+
The Variable Injector tool will inject a unique variable name for every server in the model that has the Server/SSL/ListenPort attribute.
982+
983+
# Custom special directives
984+
985+
The following directives can refine the variable injection.
986+
987+
- force:<true|false>
988+
For true, if the MBean hierarchy exists in the model, but the attribute does not, then the attribute will be added and persisted to the discovered model. The value stored in the
989+
model is the weblogic default value.
990+
991+
- variable_value:<value>
992+
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.
993+
994+
-regexp:<list of regular expression directives>
995+
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
996+
string or dictionary will be injected with a unique variable name.
997+
-pattern:<regexp pattern>
998+
the regular expression pattern to apply to the string value or map values of an attribute
999+
-suffix:<suffix name>
1000+
The suffix name to append to each resulting variable name in the variable properties file
1001+
1002+
The regexp list is useful when only a segment of a string value needs to be parameterized (making for quick manipulation of the variable properties). If more than one
1003+
pattern is specified in the regexp directive list, then a suffix MUST be added in order to generate a unique variable name.
1004+
1005+
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
1006+
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.
1007+
1008+
In the model, we expect to find a URL like the following:
1009+
1010+
```$yaml
1011+
JDBCSystemResource:
1012+
Database1:
1013+
JdbcResource:
1014+
JDBCDriverParams:
1015+
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)))'
1016+
```
1017+
1018+
We create a directive in our custom injector json file:
1019+
1020+
```json
1021+
"JDBCSystemResource.JdbcResource.JDBCDriverParams.URL":
1022+
{
1023+
"regexp": [
1024+
{
1025+
"pattern": "(?<=PORT=)[\\w.-]+(?=\\))",
1026+
"suffix": "Port"
1027+
},
1028+
{
1029+
"pattern": "(?<=HOST=)[\\w.-]+(?=\\))",
1030+
"suffix": "Host"
1031+
}
1032+
]
1033+
},
1034+
```
1035+
1036+
During the Discover Domain tool run, the pattern is applied to the URL string, and the resulting entries added to the variable properties:
1037+
1038+
- 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)))'
1039+
-
1040+
JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Host=slc05til.us.oracle.com
1041+
JDBCSystemResource.Database1.JdbcResource.JDBCDriverParams.URL--Port=1521
1042+
1043+
## Selecting specific MBean names for variable injection
1044+
1045+
The final custom directive allows you to explicitly define which named entries for an MBean in the model you wish to inject properties. For instance, you might wish to parameterize an attribute for a specific server, or for all the managed servers.
1046+
To define a list of one or more names of an MBean, add a user directive to the injector keyword value. The user directive is added to the end of an MBean between brackets. For instance, to select only the admin server named AdminServer, add the
1047+
user directive to the Server MBean - Server[AdminServer]. To select servers soa_server1 and soa_server2 from the model, create the injector key Server[soa_server1,soa_server2]
1048+
1049+
The injector tool recognizes two KEYWORDS for a user list, MANAGED_SERVERS (all the managed servers in the model) and ADMIN_SERVER (The admin server in the model).
1050+
1051+
A custom injector to parameterize the admin server SSL listen port is:
1052+
1053+
```json
1054+
{
1055+
"Server[ADMIN_SERVER].SSL.ListenPort": {},
1056+
}
1057+
```
1058+
1059+
A sample of a model_variable_injector.json file and a custom injector json file are installed in the <WLSDEPLOY>/samples directory.
1060+
1061+
8481062
## Downloading and Installing the Software
8491063

8501064
The Oracle WebLogic Server Deploy Tooling project repository is located at [`https://github.com/oracle/weblogic-deploy-tooling`](https://github.com/oracle/weblogic-deploy-tooling). Binary distributions of the `weblogic-deploy.zip` installer can be downloaded from the [GitHub Releases page](https://github.com/oracle/weblogic-deploy-tooling/releases). To install the software, simply unzip the `weblogic-deploy.zip` installer on a machine that has the desired versions of WebLogic Server installed. After being unzipped, the software is ready to use, just set the `JAVA_HOME` environment variable to point to a Java 7 or higher JDK and the shell scripts are ready to run.

0 commit comments

Comments
 (0)