Database Reference
In-Depth Information
Other than the standard documentation in the Oracle
Enterprise Manager Cloud Control Extensibility
Programmer's Reference
(Chapter 2, Section 2.5), more details can be found in the EDK API reference at
<EDK>/doc/partnersdk/mrs/emcore/agentPluginMetadata/
. This XML API documentation is generated from the
XML Schema that defines the structure of this XML—what elements can exist where and how many, what their
attributes are, and which ones are optional, as well as sparse comments that you would, nevertheless, find useful for
elements that are not documented anywhere else.
At this point, there have been enough opportunities already to make plenty of mistakes. Fortunately, the EDK
provides validation tools that can help us make sure our definitions are syntactically and semantically correct. For
example, it will catch malformed XML files as well as mismatched plug-in IDs. Listing 10-7 demonstrates a sample
validation command line and the successful validation output. The output file referenced at the end contains more
details. Note that packaging a plug-in into an OPAR file performs explicit validation before packaging.
Listing 10-7.
Plug-in Validation Example
[oracle@em12c2 oracle.samples.xsh1]$ empdk validate_plugin -stage_dir plugin_dist
Validating Plugin Xml : Passed
Validating Plugin Structure: Passed
Validating Metadata Syntax: Passed
Validating Metadata Semantic: Passed
Validating Embedded SQL strings in meta data: Passed
Plugin Validation : Passed
Validation Report generated to: /home/oracle/edk/samples/plugins/oracle.samples.xsh1/./plugin_
validation_report_121127.txt
Note that if you remove the
Readme
element, for example, the validation will pass with warnings because this
element is optional in the XML Schema, so syntactically everything is correct, but the EDK has a semantic rule that
this element should be present as a matter of best practices. I use the staging area of the host sample from the EDK,
but you can also start your own staging area by using the preceding XML content and go along in parallel.
Now that validation has succeeded, you can move onto creating the core structure: the target type metadata.
Target Type Metadata
Target type metadata defines the basic structure of the plug-in—its properties, metrics, and how to collect them. This
is an absolute minimum for creating a new target type. Target type metadata is defined in a single XML file placed in
the
<stage>/oms/metadata/targetType
directory. Oracle's most recent recommendation is to name the file after the
plug-in ID by using the
vendorID_productID_PluginTag.xml
template. The previous naming convention was after
the target type ID with an added
.xml
extension, but in general, it can be any file name. I recommend calling the target
type metadata file by using the target type, because you can package more than one target type in the same plug-in.
You also need to provide the same XML file in the agent area under the
<stage>/agent/metadata
directory, which is
subsequently referenced from
plugin_registry.xml
, as you learned earlier. On Unix/Linux servers, I simply create a
symbolic link from the agent area to the master copy in the OMS area. This way, I never forget to sync them up. (If you
do forget to synchronize the copies, as I did few times, troubleshooting can be a huge time sink. That's when I moved
to symbolic links.)
The general structure of the target type metadata looks like Listing 10-8.
