BEA Worldwide Education and Readiness
Ed.Lab: Education Lab Framework Developer Guide Version 9.0
BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed,
Table of Contents Table of Contents ............................................................................................................3 About This Document ..................................................................................................5 1. Lab Framework ...........................................................................................................7 1.1 Description.............................................................................................................7 1.2 Course Layout .......................................................................................................7 2. Getting Started ............................................................................................................9 2.1 Default Configuration .............................................................................................9 2.2 Lab-Specific Configuration .....................................................................................9 2.3 Shell Scripts.........................................................................................................10 2.4 Start a New Lab ...................................................................................................10 2.5 Continue an Existing Lab .....................................................................................11 2.6 Set Up a Lab Solution ..........................................................................................12 2.7 Continue your Current Work.................................................................................13 2.8 Start a New Demo................................................................................................13 2.9 Logs.....................................................................................................................14 3. Lab Development ......................................................................................................15 3.1 Lab Layout ...........................................................................................................15 3.2 WebLogic Server Domains ..................................................................................16 3.2.1 Domain Templates ........................................................................................16 3.2.2 Domain Folders .............................................................................................17 3.2.3 Dynamic Server Updates...............................................................................18 3.2.4 Common Domain Files ..................................................................................19 3.3 Applications .........................................................................................................20 3.3.1 Application Archives ......................................................................................20 3.3.2 Application Folders ........................................................................................21 3.3.3 Common Application Files .............................................................................22 3.3.4 Non-J2EE Applications ..................................................................................22 3.4 Databases............................................................................................................23 3.4.1 Database Servers..........................................................................................23 3.4.2 Dynamic Database Updates ..........................................................................24 4. Demo Development...................................................................................................25 4.1 Demo Layout .......................................................................................................25 4.2 WebLogic Server Domains ..................................................................................26 4.3 Applications .........................................................................................................26 4.4 Databases............................................................................................................26 5. Lab Framework Internals ...........................................................................................27 5.1 Dispatcher............................................................................................................27 5.2 Event Handlers ....................................................................................................28 5.3 Tasks ...................................................................................................................29 5.3.1 Set Current Lab .............................................................................................29 5.3.2 Backup Domain Work ....................................................................................29 5.3.3 Initialize Domain ............................................................................................29 5.3.4 Restore Domain ............................................................................................30 5.3.5 Start Server ...................................................................................................30 5.3.6 Update Server ...............................................................................................30 5.3.7 Backup Application Work...............................................................................30 5.3.8 Initialize Application .......................................................................................31
Page 3 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed,
5.3.9 Deploy Application.........................................................................................31 5.3.10 Restore Application .....................................................................................31 5.3.11 Start Database ............................................................................................31 5.3.12 Stop Database.............................................................................................32 5.3.13 Update Database.........................................................................................32 5.4 Custom Task Development..................................................................................33 6. Course Installer .........................................................................................................34 6.1 Installer Layout ....................................................................................................34 6.2 Install a Course....................................................................................................35 6.3 Installation Events................................................................................................36 6.4 Prepare a Course for Installation..........................................................................36
Page 4 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed,
About This Document This document describes the intended use of the Ed.Lab Lab Framework and Course Installer. It is intended for course developers who must implement lab exercises and demonstrations using the features of Ed.Lab, as well as those who wish to extend or customize the default framework implementation. Updated: October 13, 2005
Page 5 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
1. Lab Framework 1.1 Description The Lab Framework aims to supply course developers with a comprehensive set of tools to aid in the development of standardized labs and student environments. The Lab Framework is implemented as a collection of software components that can be easily extended and customized by course developers and others as necessary. Students leverage the Lab Framework to prepare their course environment as well as to initialize their environment to begin individual exercises.
1.2 Course Layout Upon successful execution of the Course Installer, all of the resources required to run the course and its exercises will be copied to the student’s local file system. A copy of the Lab Framework will be present along with any course and lab-specific files. The high-level organization of a typical course is shown below:
The root location, student/mycourse is arbitrary, and is selected by the student during course installation. The bin folder contains native shell scripts that are used to execute commands on the Lab Framework. These scripts are dynamically generated by the Course Installer, based on input supplied by the student. The edlab folder contains a copy of the Lab Framework software, including scripts, source, and configuration files. These resources can be customized by the developer directly, or can be overridden for each lab or demo. The demos folder contains the resources for 0 or more course demonstrations, such as servers and applications. Each demo is located under a specific child folder. The labs folder contains the resources for 0 or more course exercises, such as servers and applications. Each lab is located under a specific child folder. The work folder, also known as the student’s “workspace”, contains the working resources for the current lab or demo, including servers and application source. Any files that require editing for a lab will typically be done in this workspace.
Page 7 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
The optional install folder contains additional resources, such as servers and applications, which are initialization during the installation of this course. See the section entitled Course Installer for more details.
Page 8 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
2. Getting Started 2.1 Default Configuration The file edlab.properties is the default configuration file for the Lab Framework:
This file contains general settings, or properties, that are used by the Lab Framework to process commands. The properties in the file include the following information: •
The scripts, or Tasks, that are executed in response to a Lab Framework command, such as setting up a lab, lab solution, or demo.
•
The locations of required software including the BEA home, WLS home, and JDK home paths.
•
The properties of each WebLogic Server 9.0 domain used in the course.
•
The properties of each J2EE application used in the course.
•
The properties of each relational database used in the course.
Properties in this file conform to the standard Java Resource Bundle guidelines. When starting to develop a new course, it may be necessary to edit the properties associated with your WebLogic Server 9.0 installation, as shown below:
These properties will be automatically set to the student’s environment upon running the Course Installer. See the section entitled Prepare a Course for Installation for additional information.
2.2 Lab-Specific Configuration Additional Lab Framework properties can be set on a per-lab or per-demo basis through the development of a lab-specific copy of edlab.properties, as shown below:
Page 9 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
This technique can also be used to override the values of default properties, and thus to customize the default behavior of the Lab Framework. See the section entitled Lab Framework Internals for more information on customizing the Lab Framework.
2.3 Shell Scripts A collection of native shell scripts are supplied with the Lab Framework to offer a convenient method by which students can execute commands, such as setting up a new exercise. Currently, shell scripts are provided for both Windows and Linux. When starting to develop a new course, it may be necessary to edit the environment variables in these scripts that are associated with your WebLogic Server 9.0 installation, as shown below:
The values of these variables will be automatically set to the student’s environment upon running the Course Installer. See the section entitled Prepare a Course for Installation for additional information.
2.4 Start a New Lab To begin working on a new lab using the Lab Framework, perform the following steps: 1. Execute bin/prompt.cmd or bin/prompt.sh depending on your operating system. A new shell process will be started. By default, the shell will place you in the labs folder of the course. 2. Change directories to the subfolder associated with the lab you wish to begin. For example: cd lab01 3. Execute the following command from the shell: ant setup_exercise Page 10 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
4. If the previous lab already has an existing backup copy, you will be prompted and asked if you wish to replace the backup copy: Overwrite existing application backup? (y/n) y 5. Upon successful completion of the command, any lab resources will be initialized in the student Workspace. You may now begin following any further instructions for this lab, such as editing servers and applications. The default Lab Framework executes the following steps, or Tasks, in response to this command: •
If another lab is already present in the student Workspace, a backup copy is made.
•
The location of the current lab is saved.
•
Any WebLogic Server 9.0 domains associated with the current lab exercise are initialized in the Workspace.
•
Any J2EE applications associated with the current lab exercise are initialized in the Workspace.
•
Any databases configured for this lab are started, if not already running.
•
Any SQL updates to the databases configured for this lab are performed.
•
The administration server for each domain is started, if not already running.
•
Any WLST updates to the domains are performed.
•
Any applications are deployed, if not already deployed.
2.5 Continue an Existing Lab To continue working on a lab that was previously started, using the Lab Framework, perform the following steps: 1. Execute bin/prompt.cmd or bin/prompt.sh depending on your operating system. A new shell process will be started. By default, the shell will place you in the labs folder of the course. 2. Change directories to the subfolder associated with the lab you wish to continue. For example: cd lab02 3. Execute the following command from the shell: ant continue_exercise 4. If the previous lab already has an existing backup copy, you will be prompted and asked if you wish to replace the backup copy: Overwrite existing application backup? (y/n) y
Page 11 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
5. Upon successful completion of the command, any previous lab resources will be restored to the student Workspace. You may now continue following any further instructions for this lab, such as editing servers and applications. The default Lab Framework executes the following steps, or Tasks, in response to this command: •
If another lab is already present in the student Workspace, a backup copy is made.
•
The location of the current lab is saved.
•
Any WebLogic Server 9.0 domains that were previously backed up are restored to the Workspace.
•
Any J2EE applications that were previously backed up are restored to the Workspace.
•
Any databases configured for this lab are started, if not already running.
•
The administration server for each domain is started, if not already running.
2.6 Set Up a Lab Solution To begin working on the solution for a given lab using the Lab Framework, perform the following steps: 1. Execute bin/prompt.cmd or bin/prompt.sh depending on your operating system. A new shell process will be started. By default, the shell will place you in the labs folder of the course. 2. Change directories to the subfolder associated with the lab solution you wish to load. For example: cd lab01 3. Execute the following command from the shell: ant setup_solution 4. If the previous lab already has an existing backup copy, you will be prompted and asked if you wish to replace the backup copy: Overwrite existing application backup? (y/n) y 5. Upon successful completion of the command, any resources for the lab solution will be initialized in the student Workspace. The default Lab Framework executes the following steps, or Tasks, in response to this command: •
If another lab is already present in the student Workspace, a backup copy is made.
•
The location of the current lab is saved.
•
Any WebLogic Server 9.0 domains associated with the current lab solution are initialized in the Workspace. Page 12 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
•
Any J2EE applications associated with the current lab solution are initialized in the Workspace.
•
Any databases configured for this lab are started, if not already running.
•
Any SQL updates to the databases configured for this lab are performed.
•
The administration server for each domain is started, if not already running.
•
Any WLST updates to the domains are performed.
•
Any applications are deployed, if not already deployed.
2.7 Continue your Current Work While working on a lab or demo, some situation may result in the shut down of your servers or databases, such as a machine restart. To continue working on the current lab, using the Lab Framework, perform the following steps: 6. Execute bin/prompt.cmd or bin/prompt.sh depending on your operating system. A new shell process will be started. By default, the shell will place you in the labs folder of the course. 7. Change directories to your student workspace. For example: cd ../work 8. Execute the following command from the shell: ant continue_work The default Lab Framework executes the following steps, or Tasks, in response to this command: •
Any databases configured for this lab are started, if not already running.
•
The administration server for each domain is started, if not already running.
2.8 Start a New Demo To begin presenting a new course demonstration using the Lab Framework, perform the following steps: 1. Execute bin/prompt.cmd or bin/prompt.sh depending on your operating system. A new shell process will be started. By default, the shell will place you in the labs folder of the course. 2. Change directories to the subfolder associated with the demo you wish to begin. For example: cd ../demos/demo01 3. Execute the following command from the shell: ant setup_demo 4. If the previous lab or demo already has an existing backup copy, you will be prompted and asked if you wish to replace the backup copy: Page 13 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
Overwrite existing application backup? (y/n) y 5. Upon successful completion of the command, any demo resources will be initialized in the student Workspace. You may now begin following any further instructions for this demo. By default, this command is functionally equivalent to the setup_exercise event. For a description of the steps used to execute this command, see the previous section entitled Start a New Lab.
2.9 Logs For debugging purposes, each command issued to the Lab Framework generates a log file at the location edlab/logs, as shown below:
The log file is of the format edlab__.log, where: = The name of the folder from which the command was executed. For example: lab01 or demo05. = The name of the command that was issued by the student, such as setup_exercise or continue_exercise. In addition to the log file, Lab Framework messages are also sent to the Standard Output and Standard Error streams of the shell used to execute commands. Note: Any log files that were produced during course development and accidentally included in a course build will be removed by the Course Installer. Note: Some Lab Framework commands result in the execution of the WebLogic Scripting Tool (WLST) interpreter. WLST also generates log files named script.log. These files may contain additional debugging information not found in the standard Lab Framework logs.
Page 14 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3. Lab Development 3.1 Lab Layout The resources for each lab that is supplied with a course are typically placed within a child folder of the labs course directory. The organization of a typical lab folder is shown below:
The root lab folder, lab03, can be any arbitrary name. This folder is typically located under the labs course folder. Note that if the root lab folder is not placed within labs, some simple modifications to the file build.xml will also be required. The file build.xml is an Ant script that supplies students with a convenient method of sending commands to the Lab Framework, specifically to the file edlab/dispatcher.xml. Normally, this file will be identical in every lab. For more information, see the section entitled Lab Framework Internals. The exercise folder contains all of the initial resources used to set up this lab. These resources can consist of any combination of the following: •
WebLogic Server 9.0 domains
•
J2EE applications
•
SQL scripts
•
WLST scripts
•
Other resources not used directly by the Lab Framework
The solution folder contains all of the completed resources that represent the full solution to this lab. The capabilities of this folder are the same as those of the exercise folder. The backup folder represents the most recent backup copy of the work performed on this lab. This folder is automatically generated by the Lab Framework when the student transitions from this lab to another lab or demo. If the student elects to continue working on this lab at a later time, the Lab Framework will restore the contents of the backup folder to the student workspace. Note that the Lab Framework does not maintain multiple backup copies of the work performed on a single lab.
Page 15 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.2 WebLogic Server Domains A lab may require the Lab Framework to initialize 1 or more WebLogic Server 9.0 domains. A Domain typically consists of server configuration files, scripts, and default deployments. To allow the Lab Framework to launch the domain administration server automatically, each domain must contain a shell script named startWebLogic.
3.2.1 Domain Templates Domains may be packaged in the form of a template, which uses the file extension jar. Templates allow domains to be dynamically generated for the user’s current environment, and can be customized with additional user input. The Lab Framework generates a domain from a template using the WebLogic Scripting Tool (WLST). Domain templates associated with a lab exercise or solution are placed within a folder named domains, as shown below:
If a domain with the same name is already present in the student workspace, it will first be backed up and deleted. If any of the servers associated with the original domain are running, they will also be shut down. Each domain initialized by the Lab Framework must also be registered in edlab.properties. Either edit the default property file or create one that is specific to the lab. Domain properties are of the form: task.initdomain..= = The name of the domain template file, without the JAR extension. The supported domain properties are shown below:
The name property configures the name of the domain that is configured within the template. Currently, this name must match the name of template JAR file for the Lab Framework to function correctly. The username property configures the username of the domain administration account. This user must already be defined within the template. This account must also be Page 16 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
granted the correct permissions to launch, update, and shut down servers in this domain. The password property configures the password of the domain administration account. This password will overwrite any existing password configured in the domain template. The url property configures the hostname and port of the domain administration server. This URL is used by the Lab Framework to update and shut down servers in the domain. The property value must be of the form :. The optional starttime property configures the maximum time in minutes that the Lab Framework should wait for the domain administration server to start, before continuing execution. If not specified, the default time is 3 minutes.
3.2.2 Domain Folders Domain resources associated with a lab exercise or solution may alternatively be maintained directly on the file system, as opposed to using a template. Domain folders are simply copied to the student workspace by the Lab Framework. If a domain with the same name is already present in the student workspace, it will be first backed up. These domain folders are placed within a folder named domains, as shown below:
Be cautious when using domain folders. Unlike domain templates, the generated domain is not automatically configured to match the student’s current environment. Domain configuration files and scripts may need to be edited manually by the student when using this approach to initialize domains. Each domain initialized by the Lab Framework must also be registered in edlab.properties. Either edit the default property file or create one that is specific to the lab. Domain properties are of the form: task.initdomain..= = The name of the domain folder. The supported domain properties are shown below:
The name property configures the name of the domain. Currently, this name must match the name of domain folder for the Lab Framework to function correctly.
Page 17 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
The username property configures the username of the domain administration account. This account must also be granted the correct permissions to launch, update, and shut down servers in this domain. The password property configures the password of the domain administration account. The url property configures the hostname and port of the domain administration server. This URL is used by the Lab Framework to update and shut down servers in the domain. The property value must be of the form :. The optional starttime property configures the maximum time in minutes that the Lab Framework should wait for the domain administration server to start, before continuing execution. If not specified, the default time is 3 minutes. Domain folders also support the following additional properties:
The optional carryForward property tells the Lab Framework how to treat any previous work on a domain with the same name. If set to false, any previous domain work will first be backed up and deleted from the workspace. Also, any running servers in the domain will be shut down. If set to true, the domain folder contents are simply copied to the workspace, while overwriting any duplicate files. If not specified, this default value of this property is true.
3.2.3 Dynamic Server Updates In addition to initializing domain files for a given lab, the Lab Framework also supports dynamic updates to a domain after its administration server has been started successfully. Changes to a server can be made at runtime using the WebLogic Scripting Tool (WLST). This tool supports the execution of scripts written in the Jython programming language, and provides comprehensive libraries to access and update WebLogic Server 9.0 domains. Scripts that are executed against WLST use the file extension py. The Lab Framework will execute any WLST script files associated with a lab exercise or solution, provided that they are placed within the wlst folder, as shown below:
Several example WLST scripts are packaged with the Lab Framework, at the location edlab/common/wlst/examples. These examples represent typical uses of WLST during the initialization of a lab exercise or solution. Page 18 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.2.4 Common Domain Files Domains can be comprised on many files, and often require significant disk space. In many instances, only a minority of these domain files will actually be updated from lab to lab, while the majority remains unchanged. To reduce the footprint of a lab, and thus to also the footprint of the entire course, these common domain files can be removed from each lab folder, and placed within a central location in the course. This location is edlab/common/domains, as shown below:
Upon initializing a domain in the workspace, the Lab Framework will also copy any common files and folders for the same domain to the workspace as well. If a file exists in the workspace with the same name, it will not be overwritten. Furthermore, any common WLST scripts that should be executed for all lab exercises and solutions can be placed in the folder edlab/common/wlst, as shown below:
The Lab Framework shall execute these common scripts during the initialization of any lab, and in addition to any lab-specific WLST scripts.
Page 19 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.3 Applications A lab may require the Lab Framework to initialize 1 or more J2EE applications. These applications must also be deployed and targeted to a WebLogic Server 9.0 domain.
3.3.1 Application Archives J2EE Applications may be packaged as an archive, which uses one of the following file extensions, depending on the type of application: •
jar = EJB Application
•
war = Web Application
•
ear = Enterprise Application
Archived applications are normally used in labs as libraries and utilities, and are not intended to be edited by the student during the lab. Applications associated with a lab exercise or solution are placed within a folder named applications, as shown below:
If an application archive with the same name is already present in the student workspace, it will first be backed up and deleted. If the original application is already deployed, it will also be undeployed. Each application initialized by the Lab Framework must also be registered in edlab.properties. Either edit the default property file or create one that is specific to the lab. Application properties are of the form: task.initapp..= = The name of the application archive, without the extension. The supported application properties are shown below:
The domain property configures the domain to which this application will be deployed, once its administration server has started. The value of this property must correspond to a registered domain in edlab.properties. For example: task.initdomain.conv_domain.* See the section entitled WebLogic Server Domains for more information on configuring domains within the Lab Framework. If this property is not set, the application will not be deployed. The optional target property specifies the name of the server or cluster in the domain that this application should be targeted to. If not specified, the application will be targeted to the domain administration server. Multiple targets are not supported.
Page 20 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.3.2 Application Folders J2EE Applications may be deployed from a root folder, assuming the folder’s contents conform to the J2EE specification. Unlike archived applications, the contents of a deployed application folder can be easily modified by the student. If an application folder with the same name is already present in the student workspace, it will first be undeployed and backed up. Applications associated with a lab exercise or solution are placed within a folder named applications, as shown below:
Each application initialized by the Lab Framework must also be registered in edlab.properties. Either edit the default property file or create one that is specific to the lab. Application properties are of the form: task.initapp..= = The name of the application folder. The supported application properties are shown below:
The domain property configures the domain to which this application will be deployed, once its administration server has started. The value of this property must correspond to a registered domain in edlab.properties. For example: task.initdomain.conv_domain.* See the section entitled WebLogic Server Domains for more information on configuring domains within the Lab Framework. If this property is not set, the application will not be deployed. The optional target property specifies the name of the server or cluster in the domain that this application should be targeted to. If not specified, the application will be targeted to the domain administration server. Multiple targets are not supported. Domain folders also support the following additional properties:
The optional carryForward property tells the Lab Framework how to treat any previous work on an application with the same name. If set to false, any previous application work will first be backed up and deleted from the workspace. Also, any deployed applications will first be undeployed. If set to true, the application folder contents are simply copied to the workspace, while overwriting any duplicate files. If not specified, this default value of this property is true.
Page 21 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.3.3 Common Application Files J2EE Applications can be comprised on many files, and often require significant disk space. In many instances, only some of these application files will actually be updated from lab to lab, while other files remain unchanged. To reduce the footprint of a lab, and thus to also the footprint of the entire course, these common application files can be removed from each lab folder, and placed within a central location in the course. This location is /edlab/common/applications, as shown below:
Upon initializing an application in the workspace, the Lab Framework will also copy any common files and folders for the same application to the workspace as well. If a file exists in the workspace with the same name, it will not be overwritten.
3.3.4 Non-J2EE Applications Some application source may not be directly deployable to a server in its original form. This includes source that must be run first be run through a special build or packaging process, such as an Eclipse Workspace or Command-line application. Source in this form does not meet the packaging requirements of the J2EE specification, and thus the Lab Framework will fail when it attempts to deploy it to a server. There are two simple solutions to this scenario that allow these errors to be avoided: Option 1: Set domain to null Edit either the default or a lab-specific edlab.properties file. Disable deployment for an application by setting the property task.initapp..domain to the empty string (“”), where is the name of your application folder. Option 2: Disable deployment task Edit either the default or a lab-specific edlab.properties file. Remove the deployment step from one or more Event Handlers in the Lab Framework. See the section entitled Lab Framework Internals for details. However, if no additional customization is done to the Lab Framework, the student will still be required to manually perform the necessary steps to prepare and deploy this application source to a domain.
Page 22 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.4 Databases A course may require the Lab Framework to initialize 1 or more database processes. In addition to starting and stopping these processes, a database may require updates during the initialization of a given lab. The default Lab Framework implementation only supports Pointbase 5.1. Additional database vendors will require the development of custom Tasks. See the section entitled Lab Framework Internals for more information on extending the Lab Framework. Note: Although many of the sample WebLogic Server 9.0 domains use a single shell script to start all necessary processes, including servers and databases, this approach is not recommended for lab exercises. To provide more flexibility to the student, and to take full advantage of the Lab Framework features, remove any database commands from your domain shell scripts.
3.4.1 Database Servers Each database to be managed by the Lab Framework must be registered in edlab.properties. Either edit the default property file or create one that is specific to the lab. Database properties are of the form: task.startdb..= = A logical name for this database instance. The supported database properties are shown below:
The ini property configures the path and filename of the Pointbase 5.1 init file. This path is relative to the course root folder. The database server process will be started by the Lab Framework from the same location where the init file is located. The url property configures the database URL used to send commands to the database. The driver property configures the fully-qualified Java class name of the database driver used to send commands to the database. The username property configures the username of the account used to send commands to the database. This account must be granted the correct permissions to run any SQL commands associated with the lab. The password property configures the password of the account used to send commands to the database.
Page 23 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
3.4.2 Dynamic Database Updates In addition to managing database servers for a given lab, the Lab Framework also supports dynamic updates to a database after it has been started successfully. Database updates are performed using standard Structured Query Language (SQL) commands. These commands are normally batched into one or more SQL script files. SQL scripts use the file extension sql. The Lab Framework will execute any SQL script files associated with a lab exercise or solution, provided that they are placed within the sql folder, as shown below:
Databases must first be registered in edlab.properties, as described in the previous section. For each database to update, create a child folder under the sql directory, and name it the logical ID assigned to the database in edlab.properties. Place any SQL scripts to execute within this new folder. Furthermore, any common SQL scripts that should be executed for all lab exercises and solutions can be placed in the folder edlab/common/sql, as shown below:
The Lab Framework shall execute these common scripts during the initialization of any lab, and in addition to any lab-specific SQL scripts.
Page 24 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
4. Demo Development 4.1 Demo Layout The resources for each demonstration that is supplied with a course are typically placed within a child folder of the demos course directory. The organization of a typical demo folder is shown below:
The root lab folder, demo01, can be any arbitrary name. This folder is typically located under the demos course folder. Note that if the root lab folder is not placed within demos, some simple modifications to the file build.xml will also be required. Each demo folder contains all of the resources used to initialize this demo in the student’s workspace. Note that, unlike a course lab, a demo does not require separate exercise and solution folders. These resources can consist of any combination of the following: •
WebLogic Server 9.0 domains
•
J2EE applications
•
SQL scripts
•
WLST scripts
•
Other resources not used directly by the Lab Framework
The file build.xml is an Ant script that supplies users with a convenient method of sending commands to the lab framework, specifically the file edlab/dispatcher.xml. Normally, this file will be identical for every demo. For more information, see the section entitled Lab Framework Internals. The backup folder represents the most recent backup copy of the work performed on this demo. This folder is automatically generated by the Lab Framework when the user transitions from this demo to another lab or demo. If the user elects to continue working on this demo at a later time, the Lab Framework will restore the contents of the backup folder to the workspace. Note that the Lab Framework does not maintain multiple backup copies of the work performed on a single demo.
Page 25 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
4.2 WebLogic Server Domains Course demonstrations support the same Lab Framework capabilities as labs, including the initialization and updating of WebLogic Server 9.0 domains. See the section entitled Lab Development for more information.
4.3 Applications Course demonstrations support the same Lab Framework capabilities as labs, including the initialization and deployment of J2EE applications. See the section entitled Lab Development for more information.
4.4 Databases Course demonstrations support the same Lab Framework capabilities as labs, including the initialization and updating of database servers. See the section entitled Lab Development for more information.
Page 26 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
5. Lab Framework Internals The following sections describe the design and implementation of the Lab Framework. It is intended for course developers who wish to modify the default functionality of the framework, or to extend its capabilities.
5.1 Dispatcher The Dispatcher is a front controller through which all requests, or Events, to the Lab Framework are supplied by the student and processed. Based on the contents of the file edlab.properties, these Events are then routed to an appropriate Event Handler. Each Event Handler is defined by a series of Tasks, each of which is implemented as an Ant script. These Tasks are the components that do the heavy lifting in the Lab Framework. The following diagram depicts the high-level components that comprise the Lab Framework, as well as their relationships: Installer
Task Event Handler
Task
Dispatcher Event Handler
Task
Task
The Dispatcher is implemented by the Ant script edlab/dispatcher.xml. This script requires 2 primary arguments, supplied in the form of Ant properties: •
The name of the Event to process. For example: setup_exercise.
•
The path from which the Event was fired. For example: /mycourse/labs/lab01.
The Dispatcher then determines the appropriate course of action using the settings found in edlab.properties. If the path from which the Event was sent also contains a file named edlab.properties, its settings will be used as well. Any property found in the labspecific file overrides a default property with the same name.
Page 27 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
5.2 Event Handlers Each Event is associated with a specific Event Handler using edlab.properties. Event properties are of the form: event.= = The name of the event. = The name of the event handler used to process this event, whose definition is also in edlab.properties. For example: event.setup_exercise=handler1. Each Event Handler is associated with a specific list of Tasks using edlab.properties. Event Handler properties are of the form: handler.=,,… = The name of the event handler. = A comma-separated list of the names of the tasks to execute for this event handler. For example: handler.handler1=initdomain,initapp. Each Event must also specify the relative location of the resources required by the Tasks to perform their work. These resources include domains, applications, and SQL scripts. These properties are of the form: event..path= = The name of the event. = The location of any resources required to process the event. This path is relative to the location from which the event is fired. For example: event.setup_exercise.path=exercise event.setup_solution.path=solution event.setup_demo.path=.
Page 28 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
5.3 Tasks Each Task is implemented as an Ant script, and registered using edlab.properties. Task properties are of the form: task.=<scriptFile> = The name of the task. <scriptFile> = The relative path and filename of the Ant script that implements this task. The path is relative to location of the Dispatcher, which is the folder edlab. For example: task.initapp=tasks/app/init_app.xml. If the Dispatcher locates the same task implementation file within the current lab or demo, it will execute it instead of the default implementation. These lab-specific task scripts must be placed within a folder named edlab within the current lab or demo, as shown below:
5.3.1 Set Current Lab edlab/tasks/misc/set_current_lab.xml In order to correctly backup and restore the student’s workspace across multiple invocations to the Lab Framework, this task writes the location of the current lab or demo to the file edlab/currentwork.properties.
5.3.2 Backup Domain Work edlab/tasks/domain/backup_work.xml This task copies any domains in the student workspace to the folder named backup within the root of the current lab or demo. The current lab is identified using the file edlab/currentwork.properties. If a backup copy already exists for the current lab, the user is first prompted to confirm the deletion of the previous backup. If the user selects “no”, no backup copy is made.
5.3.3 Initialize Domain edlab/tasks/domain/init_domain.xml
Page 29 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
This task initializes any domain resources for the current lab or demo. Domains are placed within the student workspace. If a domain template is found, the resulting domain will be generated using the WLST script create_domain.py. If the same domain already exists in the student workspace, any running servers will first be shut down and the old domain will be removed. Server shutdown is done using the WLST script shutdown_domain.py. This behavior can be modified using the carryForward property set in edlab.properties, and whether or not the domain is in the form of a template. Lastly, this task copies any common domain files located in the folder edlab/common/domains.
5.3.4 Restore Domain edlab/tasks/domain/restore_domain.xml This task copies any domains from the folder named backup within the root of the current lab or demo to the student workspace. The current lab is identified using the file edlab/currentwork.properties. If the same domain already exists in the student workspace, any running servers will first be shut down and the old domain will be removed. Server shutdown is done using the WLST script shutdown_domain.py.
5.3.5 Start Server edlab/tasks/server/start_server.xml This task starts the administration server of each domain in the student workspace. A new process is spawned to execute the shell script startWebLogic, located under the domain root folder. The task then waits for the server to complete its startup and to open its port before returning. If the administration server is already running, no work is performed.
5.3.6 Update Server edlab/tasks/server/update_server.xml This task executes any custom WLST scripts located within the wlst folder of the lab or demo. These scripts are typically used to update a running domain, such as the configuration of a new JDBC data source or JMS queue. Any WLST scripts found under edlab/common/wlst are executed as well.
5.3.7 Backup Application Work edlab/tasks/app/backup_work.xml Page 30 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
This task copies any applications in the student workspace to the folder named backup within the root of the current lab or demo. The current lab is identified using the file edlab/currentwork.properties. If a backup copy already exists for the current lab, the user is first prompted to confirm the deletion of the previous backup. If the user selects “no”, no backup copy is made.
5.3.8 Initialize Application edlab/tasks/app/init_app.xml This task initializes any application resources for the current lab or demo. Applications, whether archived or exploded, are placed within the student workspace. If the same application already exists in the student workspace and is deployed to a running server, it will first be undeployed and the old application will be removed. Undeployment is done using the WLST script stop_app.py. This behavior can be modified using the carryForward property set in edlab.properties, and whether or not the application is archived or not. Lastly, this task copies any common application files located in the folder edlab/common/applications.
5.3.9 Deploy Application edlab/tasks/app/deploy_app.xml This task deploys each application in the student workspace to its associated domain and target. The deployment is accomplished using the WLST script deploy_app.py. If the application is already deployed, it is redeployed.
5.3.10 Restore Application edlab/tasks/app/restore_app.xml This task copies any applications from the folder named backup within the root of the current lab or demo to the student workspace. The current lab is identified using the file edlab/currentwork.properties. If the same application already exists in the student workspace and is deployed to a running server, it will first be undeployed and the old application will be removed. Undeployment is done using the WLST script stop_app.py.
5.3.11 Start Database edlab/tasks/db/start_db.xml This task starts each of the database servers registered in edlab.properties. A new JVM process is spawned for each database which executes the class com.pointbase.net.netServer. If a database is already running, no work is performed. Page 31 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
This task only supports Pointbase version 5.1, which is packaged with WebLogic Server 9.0.
5.3.12 Stop Database edlab/tasks/db/stop_db.xml This task shuts down each of the database servers registered in edlab.properties. A new JVM process is spawned which executes the class com.pointbase.tools.toolsCommander. If a database is currently not running, no work is performed. This task only supports Pointbase version 5.1, which is packaged with WebLogic Server 9.0.
5.3.13 Update Database edlab/tasks/db/update_db.xml This task executes any custom SQL scripts located within the sql/ folder of the lab or demo. The folder name determines the database against which the script is run, and thus must match the database name registered in edlab.properties. Any SQL scripts found under edlab/common/sql are executed as well.
Page 32 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
5.4 Custom Task Development Perform the following steps to implement and deploy a new Task within the Lab Framework: 1. Develop the implementation of your Task as an Ant build script. This script must contain an Ant target named execute. 2. Place the Task script within some location under the edlab course folder, or alternatively within the edlab folder for a given lab. 3. Edit the default edlab.properties file, or alternatively the edlab.properties for a given lab. 4. Add a new Task property to register your script. The path of your script file is relative to the folder edlab. For example task.myTaskName=tasks/custom/myTask.xml 5. Edit the properties for one or more Event Handlers, and add your Task name to its list of tasks. For example: handler.handler2= domainbackupwork,appbackupwork,setcurrentlab,initdomain,myTaskName The following Ant Properties are automatically defined by the Dispatcher before executing your Ant build script, and therefore can be referenced as needed: •
${edlab.coursePath} – The full path to the root folder of the course.
•
${edlab.workspacePath} - The full path to the work course folder, referred to as the student workspace.
•
${edlab.eventName} – The name of the current Event being processed, such as “setup_exercise”.
•
${edlab.eventPath} – The full path to the location from which the current Event was triggered. For example: /mycourse/labs/lab01.
•
${edlab.eventResourcePath} – The full path to the folder where resources such as domains and applications can be found for the current Event being processed. For example: /mycourse/labs/lab01/exercise.
•
${edlab.eventHandler} – The name of current Event Handler being executed, such as “handler1”.
Page 33 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
6. Course Installer The Course Installer is responsible for extracting and initializing the contents of a course from some media, such as a CD, to the student’s local file system. This process includes the initialization of any Lab Framework components to support the student’s local environment. Lastly, the Installer dispatches an event to the Lab Framework, allowing any additional course-specific processing to take place, such as initializing a WebLogic Server domain.
6.1 Installer Layout The Course Installer is comprised of the following components:
The file course.zip is an archive containing all the resources for the course, including labs, demos, and the Lab Framework. See the section entitled Course Layout for a detailed description of this file’s contents. The files install.cmd and install.sh are native scripts used to initiate the installer. These scripts attempt to detect a local JVM, and if unsuccessful will leverage the JVM provided on the media. The JVM is used execute Ant. The Ant script installer/build.xml implements the main functionality of the Course Installer: 1. Prompt the user for the location to which to install the course. 2. Prompt the user for their environment settings, including JDK_HOME, BEA_HOME, and WEBLOGIC_HOME. 3. Extract the course archive to the supplied location. 4. Update edlab.properties, pointbase.ini, and the course shell scripts with the supplied settings. 5. Dispatch the setup_course event to the Lab Framework.
Page 34 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
The files installer/install-unix.properties and installer/install-win.properties contain the default Ant settings for their respective environments. The file build.xml will load one of these files, depending on the current operating system. The folders jre-linux and jre-win contain a Java 1.5.X compliant JVM that can be used to execute the Course Installer, in the case that a local JVM is not found. The ant folder contains the Ant 1.6.X runtime and libraries.
6.2 Install a Course To run a Course Installer, perform the following steps: 1. From the course media, execute install.cmd or install.sh, depending on your operating system. A new shell process begins to execute the Installer Ant build file. 2. When prompted for the location to which the course shall be installed, supply a value or just hit Enter to accept the default. For example: Enter the location where the Course should be installed. (Default is c:\student\course) > d:\student\mycourse 3. If a course already exists at this location, you will be prompted to confirm that the previous course should be deleted: Overwrite existing course installation at d:\student\mycourse? (y/n) >y 4. When prompted for the location of your BEA home directory, supply a value or just hit Enter to accept the default. For example: Enter the location of your BEA HOME. (Default is c:\bea) > d:\bea90 5. When prompted for the location of your WebLogic home directory, supply a value or just hit Enter to accept the default. For example: Enter the location of your WEBLOGIC HOME. (Default is d:\bea90\weblogic90) > [enter] 6. When prompted for the location of your JDK home directory, supply a value or just hit Enter to accept the default. For example: Enter the location of your JDK HOME. (Default is d:\bea90\jdk150_03) > [enter] 7. When the Course Installer has completed successfully, you will be prompted to exit the installer: Press Enter to exit… > [enter]
Page 35 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
6.3 Installation Events To support any additional custom installation activities, the Course Installer provides integration with the Lab Framework. When the standard installation functionality has completed successfully, the Course Installer sends an Event named setup_course to the Dispatcher. This Event is associated with an Event Handler in the same fashion that other events are, so that the result is the execution of one or more Tasks. See the section entitled Lab Framework Internals for more information on Event Handlers and Tasks. The Course Installer triggers the setup_course event from a folder named install, which can be added to the root of course.zip. The contents of this folder are shown below:
The file build.xml is an Ant script that supplies students and the Installer with a convenient method of sending the setup_course event to the Lab Framework, specifically to the file edlab/dispatcher.xml. The applications folder contains 1 or more J2EE applications to initialize in the student workspace. See the section entitled Applications for more information on configuring applications in the Lab Framework. The domains folder contains 1 or more WebLogic Server 9.0 domains to initialize in the student workspace. See the section entitled WebLogic Server Domains for more information on configuring domains in the Lab Framework. Although not shown, an edlab folder may also be present within the install directory, to supply an edlab.properties file and/or event-specific task scripts.
6.4 Prepare a Course for Installation After a course has been developed and tested, all of its components must be archived into a file named course.zip. This file can then be combined with the Course Installer on some media, such as a CD, and supplied to students. Some general cleanup work should be done to a course in order to ensure that a student begins the course in a clean and consistent state. Some guidelines concerning these cleanup steps are listed below: 1. Delete any domains and applications from the work folder. 2. Delete any log files from the location edlab/logs. 3. Delete any backup folders found at labs/. 4. Delete any backup folders found at demos/. 5. Edit the file edlab/currentwork.properties, and set the current lab to “”. Page 36 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
Ed.Lab Developer Guide Version 9.0
6. Edit the following files, and replace your local paths with Ant tokens, using the syntax @token@: edlab/edlab.properties bin/prompt.cmd bin/prompt.sh */pointbase.ini For example: set STUDENT=@STUDENT@ set BEA_HOME=@BEA_HOME@ set JAVA_HOME=@JDK_HOME@ set WEBLOGIC_HOME=@WEBLOGIC_HOME@ These steps may be performed manually, or could easily be automated as part of some build process. For reference, A sample Ant build file that performs this cleanup functionality is provided below:
Page 37 of 37 BEA Systems, Inc. – Proprietary Worldwide Education Courseware Development
