This chapter describes the modules of the Oracle Virtual Assembly Builder introspection framework. This chapter contains the following sections:
Section 7.2, "External Common [oracle.as.assemblybuilder.external.common]"
Section 7.3, "Progress [oracle.as.assemblybuilder.progress]"
Section 7.4, "Introspector [oracle.as.assemblybuilder.introspector.api]"
Section 7.5, "Appliance [oracle.as.assemblybuilder.introspector.metadata.appliance.Appliance]"
Section 7.6, "Assembly [oracle.as.assemblybuilder.introspector.metadata.assembly.Assembly]"
Section 7.7, "Catalog [oracle.as.assemblybuilder.catalog.api]"
Section 7.8, "Introspector Plug-In Util [oracle.as.assemblybuilder.introspector.plugin.util]"
The Oracle Virtual Assembly Builder framework is made up of a number of modules. At this time, the term module is synonymous with a JAR file, but we use the term 'module' in this document. Rather than place all of the functionality in a single module, each logical grouping of functionality is in its own module. This allows you to view dependencies between each module as well as increase flexibility for deployment of the functionality in different use cases.
The goal of this section is to give a brief description of the modules that are provided in the Oracle Virtual Assembly Builder distribution. This is not a comprehensive list of all modules, only the modules that are relevant to plug-ins.
The external common module contains functionality that will be used by every Plug-In. This module contains a logger, resource bundles (used by the logger for internationalization), base exceptions, and some miscellaneous classes.
For logging within a plug-in, use the LoggerFactory to create a Logger instance. This logger instance ensures that all log messages are placed in a common log file and with consistent formatting. This logger instance also supports OJDL for properly handling diagnostic information as well as internationalization which is required by all Oracle products. Use of the LoggerFactory and logging in general is discussed in more detail in the 'Developing an Introspector Plug-In' section.
When creating new exception types within a plug-in, they must extend either AbException or AbCheckedException. AbException is a RuntimeException and AbCheckedException is an Exception. These exception types support OJDL which is a requirement of all Oracle products.
Both the logging and exception classes utilize resource bundles for internationalization. By de-fault, you need to extend the ResourceBundle class in this module for the logger to access your resources. However, there are other ways to use the logger and exceptions if you choose to store your messages in another way. This is discussed in detail in Chapter 6, "Developing an Introspection Plug-in".
The progress module contains functionality that allows a plug-in to report progress back to the user interfaces. The progress mechanism currently in place supports both predefined progress and ad-hoc progress. Using predefined progress allows the plug-in to define a list of steps that will occur during dehydration (and eventually rehydration) such that a list can be presented to a user to see which step they are currently on and how many steps are remaining. Ad-hoc progress allows the Plug-In to provide dynamically generated text back to the user that can not be determined until run-time. This is covered in detail in Chapter 6, "Developing an Introspection Plug-in".
The Introspector module contains the introspector framework and the metadata API. The Introspector module registers an IntrospectorManager service, that clients use to run introspections. It also tracks all plug-in service registrations in order to dynamically discover all available plug-ins.
This module contains all of the interfaces required to build a plug-in, so your plug-in must depend on this module.
As stated in other parts of this document, the catalog is where the metadata is stored and it is the key result of the dehydration process. The introspector module exposes a subset of the catalog API through its own metadata API. The metadata API is located in this module in the 'oracle.as.assemblybuilder.introspector.metadata' package.
An appliance is used to capture metadata for a specific installation of a server for a given product. An appliance has no children.
The following are the parts of an appliance:
The captureId is a unique key generated automatically when a new Appliance is created. It is used to correlate other Catalog artifacts back to the metadata.
Scalability info describes the minimum, maximum, target, and absolute maximum values for deploying the Appliance. Minimum is the least number of instances of this Appliance that can be deployed. Maximum is the largest number of instances of this Appliance that can be deployed. Target is the actual number of instances of this Appliance that will get created when it is deployed. Target may not be below minimum nor above maximum. Absolute maximum is the largest that maximum can be set to and is only set during dehydration, the user may not change this value at edit time. All of the other values may be set by the user at editing time.
Let's take an example where minimum is set to 1, maximum is set to 10, and target is set to 5. At initial deployment, 5 instances of the Appliance will be created. However, it will be possible for the user to add an additional 5 appliances at a later time if they decide to scale that Appliance.
Resource requirements let you define the system resources required by your appliance. Current resource requirement types: CPU_MHZ, MEMORY_MB, and NUMBER_CPUS. During deployment, these values will be used to ensure that the virtual machine where this appliance is deployed will meet or exceed the defined values.
A list of the components that are included in this Appliance. In general, this will be the same as the Plug-In's name, and will only be a single item.
The type of appliance. This can be set by the Plug-In. If not set by the Plug-In it defaults to the Plug-In name.
An Input is by definition a Socket that is listening on some Port using some set of Protocols. You must provide the Port and Protocol values when creating an Input.
An Output is a connection the product makes to some other Input. You must specify the Protocol used for the connection. You may also add Properties and System Properties to an Output if you need additional information on the Output at rehydration time. These properties are not used by OVAB directly and are simply passed along with the rest of the metadata. The difference between Properties and System Properties are that Properties are editable by the user, System Properties are not.
Properties allow the plug-in to attach arbitrary name/value pairs to an appliance for use in rehydration. User properties are editable by the user.
System Properties allow the plug-in to attach arbitrary name/value pairs to an appliance for use in rehydration. System Properties are not user editable.
A Content Resource can be thought of as a file. This allows you to attach files to the Appliance for transfer to the Deployed System. The idea is not to grab all files you need, but just what you need to modify in some way on its way from the Golden System to the Deployed System. For instance, configuration files may be converted from their original form into velocity templates. These templates will then be used during Rehydration to add back in the new Input/Output, Property, and System Property information. These converted files will then be put back into place over the original configuration files. You may also wish to generate a script during dehydration time that can then be added as a Content Resource and later executed at Rehydration time.
Note:
Content Resources are not meant as a way to transfer files from the reference system to the deployed system. Package Definitions are used to identify sets of files to be Packaged and later moved to the deployed system.
This is used to mark the metadata with a number to indicate its version. This is not a product version, but a marker. For instance, your initial release would start with version 1. If you later decided that you needed additional metadata, you would change this version to be 2. This way, when your Plug-In looks at the metadata, it can first check the version number to know what elements it should expect to exist and change its processing appropriately. The idea is that you can use a later version of your Plug-In to handle data that was generated from a previous release of the same Plug-In.
An Assembly is a container for Appliances and Sub-Assemblies. Assemblies have Inputs, Outputs, Properties, System Properties, Content Resources, and Version the same as an Appliance. The key difference between an Appliance and an Assembly is that an Assembly is a container of other Appliances and Assemblies.
The catalog module is the data model for containing all of the data relating to OVAB. Think of a catalog as a hierarchical structure where data from all phases of OVAB are stored. This data consists of metadata, content resources, package definitions, packages, templates, and deployment plans.
Metadata is where Assemblies and Appliances are persisted. Metadata originates with the introspection process and is the output of a Plug-In. This data may later be edited for deployment, but it originates from the Plug-Ins.
Packages are where the binary data collected during bundling are located. Packaging is the process that occurs directly after Dehydration and is the precursor to Template Generation. Packaging is covered in more detail in the Template Generation section below.
Templates are where deployable VM images are located. Templates are generated as a result of the Template Generation process and are used as the input into the Deployment process. Both of these are discussed in more detail in the Template Generation and Deployer sections below.
The Introspector Plug-In Util module provides a set of utilities for plug-in development. This module defines a SPIF service 'oracle.as.assemblybuilder.introspector.plugin.util.UtilFactory' for creating utility instances. See the Javadoc documentation for a full description of each utility provided by this factory class. Of particular note is the RehydrateUtil utility class which you can use during rehydration to copy files, change their permissions, run commands as a specific user, or run velocity on templates.