INTRODUCTION
When using WebSphere Application Server Community Edition there may be several XML files that you need to create as part of deploying an application. WAS-CE has the concept of “deployment plans” which describe how to deploy a Java Enterprise application to WAS-CE. Since these files may be complex any errors in syntax can cause wasted time and effort trying to deploy an application to WAS-CE.
In this article you will learn how to use the XML tools built into the Eclipse Web Tools Platform to help create these files to avoid syntax errors. Since the WAS-CE Eclipse plug-in does not naturally know how to create these files you will be using an XML tool called the XML Catalog to add the definitions for the WAS-CE related XML schemas. After doing this you can easily create XML files for WAS-CE, even using some of the visual XML editor capabilities to simplify the process.
SETUP
This article assumes you have an environment setup as described in the Getting Started with WebSphere Community Edition 2.0 and Eclipse article. If you do not yet have WAS-CE and Eclipse installed follow the steps in that article to configure the environment.
IMPORT WAS-CE SCHEMAS
The easiest way to use the WAS-CE XML schemas from Eclipse is to import them into your Eclipse workspace. This section will do that so the next section can add entries in the XML Catalog that point to the local schema files.
Start Eclipse if it is not already running. Generally this is done by executing the ‘eclipse.exe’ program or double-clicking a shortcut that points to it.
When Eclipse starts it will likely ask for a “workspace”. Use the workspace from the last article if you have one. If you don’t use an empty folder.
Make sure you are in the ‘Java EE’ perspective by selecting ‘Window -> Open Perspective -> Other’, selecting Java EE from the list and clicking OK.
To simplify the setup a file will be provided with an Eclipse project that includes the WAS-CE schemas and another file you will need for the XML Catalog in the next step. To start, click on this link and download the file. You can save it anywhere as you will import it into Eclipse in the next step.
In the menus of Eclipse select ‘File -> Import…‘.
Expand the General group and select Existing Projects into Workspace. Press the Next button.
Select the radio button next to the Select archive file option. Use the Browse button to find the location where you saved the downloaded file from earlier. Press the Finish button once your options match that below to import the project.
If you expand the project in the ‘Project Explorer’ view you should see all of the schema files that were added. If you see two ‘WAS-CE-Schema’ projects listed in the ‘Project Explorer’ view you might want to restart Eclipse to refresh so only one is listed.
Note: You may notice that many of the file names start with ‘geronimo-xxx’. This is because WAS-CE is based on Apache Geronimo and uses the same schema definitions.
ADD XML CATALOG ENTRIES
The “XML Catalog” is a tool you can use to provide Eclipse with additional XML schema definitions. Although you can add entries to this catalog manually this section will show you how to import a file that can add them automatically.
From the main Eclipse menus select ‘Window -> Preferences‘.
Expand the ‘Web and XML‘ group of preferences and select ‘XMLCatalog‘.
On the right click the Advanced button.
On the dialog that appears click the Import button.
On the next dialog that pops up expand the ‘WAS-CE-Schema‘ project, select the ‘WTP2.catalog‘ file, and click the OK button to complete the import.
In the upper section of the XML Catalog preferences expand the section for “User Specified Entries”. If you select the various entires, notice that these are the schemas for Geronimo (and WAS-CE) XML files and they link to the various schema files in the ‘WAS-CE-Schema‘ project in your workspace.
Click the OK button to close the preferences dialog.
Congratulations! You have just provided Eclipse with the definition of about 20 Geronimo/WAS-CE XML schemas simply by importing a few files. In the next sections you will learn how to use these definitions.
CREATE XML FILE FROM SCHEMAS
Now that you have imported Apache Geronimo/WAS-CE XML Schema definitions into the XML Catalog you can use them to create XML files. The easiest way to associate the schema with an XML file is to do it when the XML file is created.
First create a project to place your XML files in. You can do this by selecting ‘File -> New -> Project‘. You can use the “Genral” project type and the name of the project can be anything.
Once you have a project, right click the project in one of the Eclipse views that shows the project contents and select ‘New -> Other‘.
Expand the ‘XML‘ group in the list and select the ‘XML‘ entry. Press the Next button.
Change the name of the XML file to anything you want it to be, as long as the file extension is still .xml. If you are creating Geronimo specific XML files like deployment plans that must be a certain name you must change the name manually as Eclipse will be unaware of what the name of the file should be. Make sure that the project you created to hold the XML file is selected as the location and press the Next button.
On the next page select the ‘Create XML file from an XML schema file‘ option and press the Next button.
On the next page select the option for ‘Select XML Catalog entry‘ and choose the XML schema you need to use for the file from the list. Refer to the Geronimo or WAS-CE documentation for which schema is appropriate for your usage. In this example we are using the schema for a Geronimo/WAS-CE 2.0 web deployment descriptor.
The final screen of the wizard will give you options for how to create the XML file. Check that the element selected as the “root element” is correct as a choice that is different than the one you might want may be selected if there are multiple options. You might also want to select the various entries in the “Namespace Information” list and edit the details. You can change the prefix if you want and fill in a value for the “location hint” to get the full benefit of the XML editor in the next step. To edit the location hint browse and find the matching entry for each namespace in the XML Catalog entries. Press the Finish button when the options for creating the XML file are filled in.
Your XML file will open with the XML editor. Initially there will probably just be a root element and a number of XML namespace definitions. You will edit this file in the next section.
Note: If you are working with Geronimo/WAS-CE 2.0 XML files like deployment plans you will have to manually open them with the XML editor. You can do this by right-clicking a file and selecting ‘Open With -> XMLEditor‘. There is a “Deployment Plan Editor” that comes with the WAS-CE Eclipse plug-in but it is not currently able to edit 2.0 deployment plans. Importing the schemas to the XML Catalog will help make using the XML editor easier as shown next.
EDIT XML FILE CONTENT
The XML tools available in Eclipse are most powerful when used in conjunction with the syntax defined in a schema. Since you have imported the WAS-CE XML schemas into your workspace and added them to the XML Catalog you can now use these tools to greatly simplify editing XML files.
If you do not already have the file open from the last section open it now with the XML editor. Remember that as described in the note at the end of the last section you may need to manually open the file with the XML editor if Eclipse wants to open the file with the “deployment plan editor”.
Although the XML editor has a source view where you could type the file out you can also use the visual “design” view to edit your file. Switch to the “Design” tab along the bottom if it is not open already.
Most likely your XML file currently only has a root element and a few namespace definitions. Right click on the root element and select ‘Add Child‘. Select one of the entries from the list depending on what element you wish to add. All of the choices on the list are legal elements defined by the various schemas that are in use. This helps greatly in avoiding syntax errors.
Once other elements are added as children of the root element you can continue to right-click additional elements and add other children to create the structure of the file.
You can also right click and select ‘Add Before‘ and ‘Add After‘ to add elements at the same level as the currently selected element. You can see how the visual “Design” view makes it much easier to see the structure of the XML file.
To edit the values associated with the various elements, click in the right column next to the element value to edit. Type a new value and hit <Enter> to accept the new value. Continue to do this for all the elements you have added.
Note: Make sure that you hit <Enter> to accept the last value you have changed before saving the file, otherwise you will not save all of your changes. You should also be aware that when you add an element the default value is usually the same as the name of the element. Besides this creating potential for confusion it is likely that this default value would not be a legal value for the XML element at runtime.
You can switch to the “Source” view tab along the bottom to see the XML syntax you have created in the Design view.
REVIEW
By following the steps of this article you can now use the XML tools that are part of Eclipse to create and edit WAS-CE/Geronimo XML files, including deployment plans. You did this by first importing the WAS-CE schemas as part of a project into your Eclipse workspace. You then imported a file into the XML Catalog that defined these schemas for Eclipse. Although you could have manually added all of the required XML Catalog entries this file made it much easier. You then saw how to create and edit XML files using the syntax in the various schemas. You saw how to visually edit the XML files using the “Design” view of the XML editor which makes it easy to see and change the structure of the file.
RESOURCES
Getting Started with WebSphere Community Edition 2.0 and Eclipse