Skip to content

Commit acd9e5c

Browse files
ddsharpeddsharpe
authored
Developer guide (#410)
1 parent f9d3a48 commit acd9e5c

File tree

2 files changed

+239
-0
lines changed

2 files changed

+239
-0
lines changed

‎README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Many organizations are using WebLogic Server, with or without other Oracle Fusio
2525
- [Variable Injection](site/variable_injection.md)
2626
- [Model Filters](site/tool_filters.md)
2727
- [Downloading and Installing](#downloading-and-installing-the-software)
28+
- [Developer Guide](site/developer/developer_guide.md)
2829
- [Known Issues](KnownIssues.md)
2930

3031
## Features of the Oracle WebLogic Server Deploy Tooling

‎site/developer/developer_guide.md

Lines changed: 238 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,238 @@
1+
# Developer Guide
2+
3+
## Table of Contents
4+
- [Project Structure](#project-structure)
5+
- [Feature Implementation](#feature-implementation)
6+
- [Alias Definitions](#alias-definitions)
7+
- [Building WebLogic Deploy Tool](#building-weblogic-deploy-tool)
8+
9+
## Project Structure
10+
11+
This project is structured using the Standard Directory Layout for Maven projects, with two child modules, `core` and `installer`. In addition, there is a `samples` directory with example configurations, and the `site` directory containing project documentation.
12+
13+
The `core` module contains the main source code for the project. This includes Jython modules and Java classes, as well as typedef files, alias definitions, and the message bundle. There are unit tests related to this module.
14+
15+
Alias definitions are discussed in more detail [here](#alias-definitions).
16+
17+
The `installer` module builds the final installer ZIP file. It includes the assembly definitions, start scripts for each tool for Linux and Windows platforms, and configurations for variable injection and logging.
18+
19+
A single installer ZIP file is built under the `WLSDEPLOY_HOME/installer/target` directory.
20+
21+
There are detailed instructions for building the project [here](#building-weblogic-deploy-tool).
22+
23+
## Feature Implementation
24+
25+
This section describes how specific features of WebLogic Deploy Tooling are implemented in the source code.
26+
27+
### Creator and Deployer Class Hierarchies
28+
29+
The creation of individual folders and attributes within the `topology` section of the domain model is accomplished using subclasses of the Jython class `Creator`, in the module `wlsdeploy.tool.create.creator.py`. The `Creator` class provides base methods to recurse through nested folders in the domain model, create or update those folders, and set or update their attributes. Each subclass can override these methods to account for variations in behavior for different functional areas.
30+
31+
For example, the `SecurityProviderCreator` subclass overrides the method `_create_named_subtype_mbeans` with special processing to remove all existing security providers, and re-create them from the data in the model.
32+
33+
The update of folders and attributes in the `resources` section of the domain model follows a similar pattern, but the base class for these modules is `Deployer` in the module `wlsdeploy.tool.deploy.deployer.py`.
34+
35+
The class `TopologyUpdater` is a special subclass of `Deployer` that is used to update elements in the `topology` section after their initial creation.
36+
37+
## Alias Definitions
38+
39+
WebLogic Deploy Tool uses a set of JSON configuration files to map folders and attributes in the model to the corresponding WLST MBeans and their attributes. These mappings are referred as 'aliases' throughout the project code and documentation. Each element in the alias definition file has detailed properties that assist in this mapping.
40+
41+
The model's folder and attribute names usually match the names of the corresponding elements in WLST. For cases where the names of WLST elements may change across WebLogic Server releases, the names should match the names in the 12.2.1.3 release. The unit test `AttributesTestCase` verifies that this convention is used, and identifies a few exceptions.
42+
43+
Attributes that are introduced after the 12.2.1.3 release should, in most cases, match the name of the first WebLogic Server release in which they appear. The unit test `AttributesTestCase` will ignore these for now, because they will not be present in the 12.2.1.3 alias structure.
44+
45+
The alias definition files reside in the directory:
46+
47+
`$WLSDEPLOY_HOME/core/src/main/resources/oracle/weblogic/deploy/aliases/category_module`
48+
49+
Each definition file corresponds to a second-level folder within the model, such as `JDBCSystemResource`. Any elements below a second-level folder are defined in the file of that parent. For example, the model element `resources/JDBCSystemResource/JdbcResource/JDBCConnectionPoolParams` is described in `JDBCSystemResource.json`.
50+
51+
Top-level elements such as `topology` and `resources` are for organizational purposes, and are not represented in the alias definition files.
52+
53+
No elements in the `domainInfo` section of the model are represented in the alias definitions, because they don't correspond directly to WLST elements.
54+
55+
This example, from the file `JDBCSystemResource.json`, will be used as a reference in the descriptions below:
56+
57+
```yaml
58+
{
59+
"copyright": "Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved.",
60+
"license": "The Universal Permissive License (UPL), Version 1.0",
61+
"wlst_type": "JDBCSystemResource${:s}",
62+
"child_folders_type": "multiple",
63+
"folders": {
64+
"JdbcResource" : {
65+
"wlst_type": "${Jdbc:JDBC}Resource",
66+
"folders": {
67+
"JDBCConnectionPoolParams": {
68+
"wlst_type": "JDBCConnectionPoolParams",
69+
"folders": {},
70+
"attributes": {
71+
"CapacityIncrement": [ {"version": "[10,)",
72+
"wlst_mode": "both",
73+
"wlst_name": "CapacityIncrement",
74+
"wlst_path": "WP001",
75+
"value": {"default": "${None:1}"},
76+
"wlst_type": "integer",
77+
"get_method": "LSA"} ],
78+
"ConnectionCreationRetryFrequencySeconds": [ {"version": "[10,)",
79+
"wlst_mode": "both",
80+
"wlst_name": "ConnectionCreationRetryFrequencySeconds",
81+
"wlst_path": "WP001",
82+
"value": {"default": "${None:0}"},
83+
"wlst_type": "integer",
84+
"get_method": "LSA"} ]
85+
},
86+
"wlst_attributes_path": "WP001",
87+
"wlst_paths": {
88+
"WP001": "/JDBCSystemResource${:s}/%DATASOURCE%/${Jdbc:JDBC}Resource/%DATASOURCE%/JDBCConnectionPoolParams/${NO_NAME_0:%DATASOURCE%}"
89+
}
90+
},
91+
...
92+
```
93+
94+
### Conventions
95+
96+
Notations similar to `${Jdbc:JDBC}Resource` appear throughout this example, and other alias definition files. It is shorthand for the common situation where a value is different between offline and online WLST. The value before the colon is used in offline processing, and the value after is used for online. In this example, the value for `wlst_type` is `JdbcResource` in offline, and `JDBCResource` in online. This notation can be used for values in most places in the model. It cannot be used for key values, such as `wlst_type`.
97+
98+
### Keys for Top Level and `folders` Elements
99+
100+
These JSON keys are applicable for the top-level element (such as `JDBCSystemResource`), and each of its nested `folders` elements (such as `JdbcResource` and `JdbcResource/JDBCConnectionPoolParams`.
101+
102+
#### `wlst_type`
103+
104+
This value is the type name of the WLST MBean that corresponds to a model folder. The `${x:y}` notation described above is often used here to distinguish offline and online folder names.
105+
106+
#### `child_folders_type`
107+
108+
This value specifies how the tool will map the domain model element to one or more WLST MBeans. The values are:
109+
110+
- `single` (default) - this element represents a single MBean, and the MBean name is known.
111+
112+
- `single-unpredictable` - this element represents a single MBean, but the MBean name must be derived at runtime.
113+
114+
- `multiple` - this element contains multiple named elements (such as `dataSource1`, `dataSource2`), and each represents a single MBean.
115+
116+
#### `folders`
117+
118+
Nested WLST MBean types for the current MBean are listed here. Each has a domain model type name, followed by its own JSON keyed elements.
119+
120+
#### `wlst_attributes_path`
121+
122+
This key element specifies the name of the path expression used for navigating to the MBean attributes folder. The actual path expression is defined later in the `"wlst_paths": { }` element.
123+
124+
#### `wlst_paths`
125+
126+
The dictionary key defines the various WLST path values used elsewhere in this folder's definition. Each entry maps a name to a full WLST MBean path. In this example, `JDBCConnectionPoolParams` has a single path:
127+
128+
`"WP001": "/JDBCSystemResource${:s}/%DATASOURCE%/${Jdbc:JDBC}Resource/%DATASOURCE%/JDBCConnectionPoolParams/${NO_NAME_0:%DATASOURCE%}"`
129+
130+
The `%DATASOURCE%` text is token placeholder. It will be replaced with the name of the actual data source by the tool.
131+
132+
### Keys for `attributes` Elements
133+
134+
Each child of an `attributes` element represents a single MBean attribute, and its key is the corresponding model name, such as `CapacityIncrement`. It contains at least one description element with the JSON keys below. There may be multiple description elements for cases where the configuration varies for different WebLogic Server version ranges, or varies between offline and online WLST.
135+
136+
#### `version`
137+
138+
This key element defines the applicable versions for a particular MBean attribute description. Maven versioning conventions are used to describe ranges and limits. For example:
139+
140+
`"version": "[10,)"`
141+
142+
Specifies that an MBean attribute description is relevant for WebLogic Server version 10 and later
143+
144+
#### `wlst_mode`
145+
146+
This key element specifies the WLST modes that are applicable for an MBean attribute description. The value can be "offline", "online", or "both".
147+
148+
#### `wlst_name`
149+
150+
This key element specifies the WLST name of the MBean attribute.
151+
152+
#### `wlst_type`
153+
154+
This key element specifies the data type used to set the WLST MBean attribute. Valid values are ```integer```, ```long```, ```string```, ```delimited_string```, ```boolean``` and ```jarray```. If the `wlst_read_type` is not set, this is also the data type used to read the value from WLST.
155+
156+
#### `wlst_read_type`
157+
158+
This key element specifies the data type used to read the WLST MBean attribute. If it is not specified, the value of `wlst_type` is used for the read.
159+
160+
#### `get_method`
161+
162+
This key element specifies which method should be used for retrieving the value the MBean attribute. Valid values are:
163+
164+
- `GET` use the WLST get method to retrieve the value of the attribute
165+
- `LSA` use ls(type='a') to retrieve the value of the attribute
166+
- `NONE` do not retrieve the attribute value
167+
168+
#### `preferred_model_type`
169+
170+
This key element specifies the preferred data type that should be used to put data in the model during discovery. As an example, list values can be represented in the model as comma-separated text, such as `"value1, value2"`, or as a YAML list, such as `["value1", "value2"]`. If the list values can contain commas, it is preferred to use a YAML list.
171+
172+
#### `wlst_path`
173+
174+
This key element specifies the name of the path expression used for navigating to the MBean attribute's folder. This name maps to an entry in the parent folder's `"wlst_paths": { }` list.
175+
176+
#### `value`
177+
178+
This key element is used to specify the default value of the MBean attribute. For example:
179+
180+
`"value": {"default": "${None:1}"}`
181+
182+
#### `set_method`
183+
184+
For cases where attributes cannot be set with simple types, it may be necessary to use a custom method to set the value. For example, most `Target` attributes require their values to be set as lists of MBeans, in online mode. This may be defined as:
185+
186+
```yaml
187+
"attributes": {
188+
"Target": [ {
189+
"set_method": "MBEAN.set_target_mbeans",
190+
"set_mbean_type": "weblogic.management.configuration.TargetMBean"} ],
191+
},
192+
```
193+
194+
The method `set_target_mbeans` directs the tool to call the Jython method `attribute_setter.set_target_mbeans` to set this value.
195+
196+
#### `set_mbean_type`
197+
198+
When a `set_method` key is specified, it may be required to specify the MBean type for the set method to use (see the example under `set_method`).
199+
200+
## Building WebLogic Deploy Tool
201+
202+
### Prerequisite
203+
204+
You will need the following software installed in your local build environment
205+
206+
1. Oracle WebLogic Server installation version 12.2.1 and later
207+
2. JDK version 8
208+
3. Maven 3 and later
209+
210+
### Specifying the WLST location
211+
212+
Execution of the unit tests requires a WebLogic Server installation, because the tests must be run within WLST.
213+
214+
The WLST directory can be specified in one of two ways:
215+
216+
- Specify the `-Dunit-test-wlst-dir=<wlst-directory>` on the mvn command line.
217+
218+
- Create a file `.mvn/maven.config` file in the project directory, containing a single line with the `-Dunit-test-wlst-dir=<wlst-directory>` value. The `.mvn` directory contains a `maven.config-template` file that can be copied and used as a starting point.
219+
220+
In these cases, `<wlst-directory>` refers to the fully-qualified path to the WLST script (`wlst.sh` or `wlst.cmd`).
221+
222+
If you are using an IDE for development and building, creating a `maven-config` file will allow some Maven tasks to be performed within the IDE.
223+
224+
### Build Commands
225+
226+
If you are making changes to the project, you can build the project using this command line:
227+
228+
`mvn -Dunit-test-wlst-dir=<wlst-directory> clean install`
229+
230+
This will build the entire project and run the unit tests. Omit the `-Dunit-test-wlst-dir=` argument if you have created a `maven.config` file, as described above.
231+
232+
If you are not making changes and are only interested in building the latest version, then you can skip the unit tests, and avoid validation of the WLST location, using this command line:
233+
234+
`mvn -Denforcer.skip -DskipTests clean install`
235+
236+
The option `-Denforcer.skip` prevents the Maven Enforcer plugin from verifying the JDK version, and checking that the WLST directory is specified.
237+
238+
The resulting installer ZIP file built is under the `WLSDEPLOY_HOME/installer/target` directory.

0 commit comments

Comments
 (0)