A domain contains configuration information for a BEA WebLogic Server instance. It has configuration information about servers, clusters, and machines. A domain also contains configuration information about resources such as Java DataBase Connectivity (JDBC) connection pools, JDBC data sources, connection factories, and Java Message Service (JMS) queues. In addition, it contains configuration information about the applications deployed to the instance. The domain configuration information is persisted in a config.xml file. In this article, I evaluate various strategies for WebLogic domain configuration.
The config.xml can be directly manipulated (e.g., hand-editing the file). However, most tools evaluated in the article will manipulate the config.xml indirectly. Most tools (e.g., WebLogic Console) manipulate Java Management eXtension (JMX) Management Beans (MBeans). The WebLogic Server instance persists the state of the MBeans in the config.xml file.
Domain Configuration and JMX
The config.xml file contains persistent information about a WebLogic Server instance. When a WebLogic Server instance is started, WebLogic Server reads the config.xml file and deploys the resources and applications. The resources and applications have corresponding JMX MBeans. The server exposes configuration information via these MBeans. There are many different types of MBeans. In this article, I focus on MBeans that correspond to entries in the config.xml file.
When an attribute value of an MBean is changed at runtime, the new value is made persistent by storing it in the config.xml file. For example, when an MBean attribute value is changed in the WebLogic Server Console, the attribute value is also saved in the config.xml file. Thus, the configuration attribute value is available between server restarts since the configuration attribute value is persisted in the config.xml file.
The following section describes different alternatives for domain creation and configuration, and classifies the different options available.
Options, Options, and More Options
Fortunately, many different ways to create and configure a domain are available. The most common way to create a domain is through the Domain Configuration Wizard and the most common way to configure the domain is by using the WebLogic Console. Many other alternatives are possible, including:
- Using domain configuration wizard
- Using domain configuration template
- Using silent scripts
- Using WLShell scripts
- Using WLST scripts
- Using Java code and the JMX Application Programming Interface (API) directly
- Using a token replacement (e.g., Bedrock)
- Using weblogic.Admin command
- Using wlconfig and wldeploy Ant tasks
- Hand-editing the config.xml file
The following is a way to classify the above options based on the technique utilized for domain configuration:
- Manual: WebLogic Console, Complete Domain Configuration Wizard
- Template: Custom token replacement scripts (e.g., using Ant), Bedrock, Complete Template, Extension Template
- Scripting: Silent, WLShell, WLST, Ant
- Programmatic using Java
Another way to classify the above options is by whether they ship with the WebLogic platform:
- Included (and supported): WebLogic Console, Complete Domain Configuration Wizard, Complete Template, Extension Template, Silent Script, Ant
- Additional: WL Shell, WLST, Custom token replacement scripts, Bedrock
Yet another way to classify these options is by whether they make changes while the server is online or offline. Online changes are made while an instance of the server is running. The online changes are made to JMX MBeans and persisted to config.xml file by the server. Modifying the config.xml directly while the server is running is not recommended!
- Online: WebLogic Console, ANT, WLST
- Offline: Complete Domain Configuration Wizard, Complete Template, Extension Template, silent scripts, WLShell, custom token replacement scripts, Bedrock
In order to demonstrate various strategies for domain configuration, you will create a domain and make changes to it.
High-Level Objectives
You will achieve the following objectives using different strategies for domain creation and configuration. Please do not follow these steps right now. I will ask you to create and configure the domain later employing a different strategy each time.
- Create a WebLogic Workshop domain
- Change the server debug level to info.
- Change the server to enable debug to stdout
- Configure a JDBC Connection Pool named semJDBCConnectionPool
- Configure a JDBC data source named jdbc/semJDBCDataSource with JNDI name jdbc/semJDBCDataSource
- Configure a JMS Connection Factory named semJMSConnectionFactory
- Configure a JMSJDBCStore named semJMSJDBCStore
- Configure a JMSServer named semJMSServer
- Configure semJMSServer's store to semJMSJDBCStore
- Configure a JMS Queue named PersonQueue with JNDI name jms/PersonQueue
- Deploy the sample application: SEMApp Enterprise ARchive (EAR)
- Verify the domain configuration by testing the application
For each strategy, certain steps such as domain creation, database configuration, and verifying the configuration are common. The following sections describe these steps.
Domain Creation
Follow these steps to create a WebLogic Workshop domain using the Domain Configuration Wizard. Do not perform these steps right now. I will ask you to perform these steps later when I explain the different strategies in detail.
- Launch Domain Configuration Wizard (e.g., on Windows select Start > All Programs > BEA WebLogic Platform > Configuration Wizard)
- Select Create a new WebLogic Configuration and click Next
- Select Basic WebLogic Workshop Domain and click Next
- Select Express and click Next
- Specify User name as system
- Specify User password and Confirm user password as password and click Next
- Select Development Mode and click Next
- Specify Configuration Name as something meaningful and click Create
- Click Done
Before you can configure the domain, you need to configure the database. The database configuration occurs after the domain is created, but before the domain is configured.
Database Configuration
All the examples use PointBase as the database. Starting an instance of WebLogic Server (of Workshop Domain) also starts PointBase. Set up user, schema, and tables in that instance of PointBase. Do not perform these steps right now. I will ask you to perform these steps later when I explain the different strategies in detail.
- Verify that an instance of WebLogic Server is running
- Launch PointBase Console (e.g., on Windows select Start > All Programs > BEA WebLogic Platform > Examples > WebLogic Workshop > PointBase Console)
- In the Connect to the database dialog specify the following
- Verify that the database URL is jdbc:pointbase:server://localhost:9093/workshop
- Verify User as WebLogic
- Specify Password as WebLogic
- Create a new user (e.g., Ctrl + u) named sem with password as sem
- Disconnect from the database (DBA Menu and Disconnect from Database)
- Connect to database (DBA Menu and Connect to Database or F3) using sem as the User and sem as the Password
- Create a schema (e.g., Ctrl + h) named sem
- Copy and paste contents of db/sem.sql into Enter SQL Commands window
- Select Execute All toolbar item
- Verify that sem schema is populated with tables
Once the domain is created, the database is configured, and the domain is configured with resources and the sample application, the set-up needs to be verified.
Verifying the Domain Configuration
To verify that the domain is properly created and configured, run simple JUnit tests. The included source code example contains a sample application as well as an Ant file that runs JUnit tests. Copy sample-build.properties to build.properties and edit the entries in build.properties to suit your environment. The creation of build.properties needs to happen only once. I will ask you to invoke the following command later, once you have created and configured a domain.
ant - v code fact.
If the tests run successfully, then the application is deployed properly and the resources are configured correctly. If there are any exceptions and the tests fail, then the application or the resources are not configured or deployed correctly. Carefully review and analyze the stack traces and proceed to debug the problem.
Once the tests run successfully, shut down the WebLogic Server instance e.g., the domain directory/stopWebLogic.bat or sh). Always shut down the WebLogic Server instance using the script instead of drastic means such as ctrl+c.
Manual Express Configuration
Using the steps described in the Domain Creation section, create a new domain with SEMDomain-Manual-Express as the Configuration Name. Start the WebLogic Server instance and use the steps described in the Database Configuration section to configure the database.
On many different projects, I have successfully done manual configuration using the WebLogic Server Console.
Changing the Logging Level
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Servers / cgServer
- Select Logging tab
- Check Debug to Stdout checkbox
- Select Stdout Severity Threshold as Info from the drop down list
- Select Apply
Configuring the Connection Pool
- Make sure WebLogic Server is running.
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services/JDBC/Connection Pools
- Select Configure a new JDBC Connection Pool
- Select PointBase from the Database Type dropdown list
- Select PointBase's Driver (Type 4) Versions: 4.X from Database Driver
- Select Continue
- Specify Name as semJDBCConnectionPool
- Specify Database Name as workshop
- Specify Host Name as localhost
- Specify Port as 9093
- Specify Database User Name as sem
- Specify Password as sem
- Specify Confirm Password as sem
- Select Continue
- Test the driver configuration
- Create and deploy
Configuring the DataSource
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services / JDBC / Data Sources
- Select Configure a new JDBC data Source
- Specify Name as jdbc/semJDBCDataSource
- Specify JNDI Name as jdbc/semJDBCDataSource
- Select Emulate Two-Phase Commit for non-XA Driver.
- Select Continue
- Specify Pool Name as semJDBCConnectionPool
- Select Continue
- Target the data source by clicking on Create
Configuring the JMS Connection Factory
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services / JMS / Connection Factories
- Select Configure a new JMS Connection Factory
- Specify Name as semJMSConnectionFactory
- Specify JNDI Name as jms/semJMSConnectionFactory.
- Select Create
- Target and deploy on cgServer
- Select Configuration tab
- Select Transactions sub tab
- Select XA Connection Factory Enabled
- Select Apply
Configuring the JMS JDBC Store
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services / JMS / Stores in the left navigation pane
- Select Configure a new JMS JDBC Store
- Specify Name as semJMSJDBCStore
- Select Connection Pool as semJDBCConnectionPool
- Select Create
Configuring the JMS Server
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services/JMS/Servers in the left navigation pane
- Select Configure a new JMS Server
- Specify Name as semJMSServer
- Specify Persistence Store as semJMSJDBCStore by selecting it from the dropdown list
- Select Create
- Target the semJMSServer to the cgServer
Configuring the JMS Queue
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services/JMS/Servers/semJMSServer /Destinations in the left navigation pane
- Select Configure a new JMS Queue
- Specify Name as PersonQueue
- Specify JNDI Name as jms/PersonQueue
- Select create
- Select the Redelivery sub tab
- Specify Redelivery Limit as 3
- Select Apply
Now you are done configuring the application resources. However, before you can deploy the application, you still need to configure workshop-related resources.
Configuring Workshop-Related Resources
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Services/JMS/Servers/semJMSServer/ Destinations in the left navigation pane
- Select Configure a new JMS Queue
- Specify Name as SEMAppWeb.queue.AsyncDispatcher_error.
- Specify JNDI Name as SEMAppWeb.queue.AsyncDispatcher_error
- Select Create
- Select the Redelivery sub tab
- Specify Redelivery Limit as 0
- Select Apply
- Select Services/JMS/Servers/semJMSServer/ Destinations in the left navigation pane
- Select Configure a new JMS Queue
- Specify Name as SEMAppWeb.queue.AsyncDispatcher
- Specify JNDI Name as SEMAppWeb.queue.AsyncDispatcher
- Select Create
- Select the Redelivery sub tab
- Select Error Destination as SEMAppWeb.queue.AsyncDispatcher_error
- Select Apply
You are now ready to deploy the application.
Deploying the Application
- Make sure WebLogic Server is running
- Launch the WebLogic Server Console (e.g., http://localhost:7001/console)
- Log into the Console
- Select Deployments/Applications in the left navigation pane
- Select Deploy a new Application
- Browse to the location of the SEMApp.ear file
- Select SEMApp.ear
- Select Continue
- Select Deploy
Once the application is successfully deployed, restart the server. Run the tests as described in the Verifying the Domain Configuration section.
Other manual strategies are possible using the Domain Configuration Wizard. One option is to create and configure a brand new domain by selecting the Custom (instead of the Express) option. When you are prompted to create resources such as JDBC Connection Pools in the wizard, follow the steps to create and deploy the resources. Another option is to configure an already created domain using the Domain Configuration Wizard. In the very first step of the Domain Configuration Wizard, select Extend an existing WebLogic configuration. Creating the domains as described above is left as an exercise for you. However, not all of the configuration is possible using these strategies, such as configuring a destination's Redelivery attribute.
In order to use the manual strategies successfully, a project needs to maintain a configuration guide. The configuration guide contains the step-by-step instructions as described above. However, the manual process is tedious and time consuming. Setting up another domain takes extra time and effort. Moreover, the process is error-prone. Small configuration errors, such as misspelling a JNDI name, can lead to serious troubleshooting and debugging.
Automated options to create and configure a domain are preferred. Java is a powerful language and the MBeans can be directly manipulated with it. However, this approach is too low level. There are alternative approaches such as templating and scripting. In manual templating, the config.xml is templated with tags. The tags are later replaced with actual values. The manual templating approach requires a very deep and thorough understanding of config.xml file. I have used manual templating on some projects. Bedrock is an Ant-based tool that supports such templating. However, Bedrock does not seem to be actively maintained. Another important templating technique is using a domain template. This technique does not require an in-depth knowledge of the config.xml. The creation of templates is nicely supported via the Configuration Template Builder tool. The next section discusses automating domain configuration via templating using the Configuration Template Builder tool.
Domain Template
When you created the domain manually, you used the workshop template. But, what is a template? A template is a Java ARchive (JAR) file that contains configuration information; a relevant snippet of config.xml file. There are two types of templates: complete and extension. With a complete template, a new domain is created using the template. The workshop template used above is an example of a complete template. With an extension template a domain is extended. The DefaultWebApp template used later is an example of an extension template.
How do you create a template? A special tool named Configuration Template Builder helps. A template, either complete or extension, is created in two ways. First, a template is an extension to another extension template. Second, a template is based on an existing domain. In the next section, you will create a complete template based on an existing domain.
Complete Template
In this section, I will illustrate creation of a complete template based on an existing, preconfigured, and working domain. Follow these steps to create a complete template.
- Launch Configuration Template Builder (On Windows select Start > All Programs > BEA WebLogic Platform > Other Development Tools > Configuration Template Builder)
- Select Create a Configuration Template and click Next
- Select Basic WebLogic Workshop Domain and click Next
- Select an existing, preconfigured, and working SEM domain (e.g., SEMDomain-Manual-Express) and click Next
- Specify Name as SEMTemplate-Complete
- Specify Author (e.g., Bart)
- Specify Category (e.g., SEM)
- Specify Description and click Next
- Take the defaults by clicking Next on the subsequent dialogs
- In Create Template, specify a name for the template (e.g., SEMTemplate-Complete), observe and remember the location of the template JAR file %BEA_HOME%/user_templates/, Click Create
- Click Done
Now, create a new domain based on the complete template. Follow these steps to create a complete domain.
Domain Creation Based on Complete Template
- Launch Domain Configuration Wizard (On Windows select Start > All Programs > BEA WebLogic Platform > Configuration Wizard)
- Select Create a new WebLogic Configuration and click Next.
- Instead of selecting one of the default templates, browse to location of complete template (%BEA_HOME%/user_templates)
- Select SEMTemplate-Complete and click Next.
- Take the defaults by clicking Next on the subsequent dialogs
- Specify Configuration Name as something meaningful (e.g., SEMDomain-Complete) and click Create
- Click Done
However, starting a WebLogic Server instance of this domain fails! The encrypted security credentials conflict. Make the following changes manually to the config.xml file.
Changes to config.xml
- Change SecurityConfiguration element's Credential attribute's value to ""
- Change EmbeddedLDAP element's Credential attribute's value to ""
- Change cgPool Password attribute's value to "weblogic"
- Change semJDBCConnectionPool Password attribute's value to "sem"
Follow the steps described in Verifying the Domain Configuration to verify that the domain is working properly.
Another important templating strategy is to create an extension template; for example, an extension template that extends DefaultWebApp template and configures all the necessary resources. Creating the extension template, creating a domain, and extending the domain with the extension template are left as an exercise for you.
Conclusion
Domain configuration by hand-editing the config.xml file is error-prone and dangerous. On the other extreme, domain configuration by writing Java code is tedious. Common alternatives include domain configuration by using the WebLogic Console or Domain Configuration Wizard. However, both alternatives are manual and likely to be repetitive and time-consuming. In search of automated solutions, I evaluated templating. Please stay tuned for my next article, which will evaluate scripting strategies. I hope this article helps you make a knowledgeable and informed decision about choosing tools and techniques for automating domain configuration.
References
To discuss the article and ask questions start here: www.bartssandbox.com. Free membership is required.
