Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM

Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM

from ibm.com More from this publisher

25.03.2013 Views

Hit the ground running with AIDE, Part 1: Building a touchpoint Skill Level: Intermediate Stephen B. Morris CTO Omey Communications 18 Apr 2006 This tutorial, the first in a series on the IBM Autonomic Integrated Development Environment (AIDE), shows how you can get up and running quickly with the IBM AIDE toolkit. Discover touchpoint creation, modification, and deployment and learn about the internals of the touchpoint in relation to the underlying model. Section 1. Before you start Learn what to expect from this tutorial and how to get the most out of it. About this series This tutorial is the first in a series that describes techniques for the development of autonomic computing technology using the IBM® Autonomic Integrated Development Environment (AIDE) toolkit. This tutorial was written as a type of one-stop shop for new AIDE users; its goal is to get you comfortable using the AIDE toolkit, the associated technologies, the design philosophy, and the examples that come bundled with the toolkit. The remaining tutorials in the series will describe touchpoint deployment on several platforms, including Linux®, MySql, and Apache. By the end of the series, you should have a sound understanding of the development of autonomic technology on generic and open source platforms. Building a touchpoint Trademarks © Copyright IBM Corporation 2006. All rights reserved. Page 1 of 23

Hit the ground running with AIDE, Part 1: Building

a touchpoint

Skill Level: Intermediate

Stephen B. Morris

CTO

Omey Communications

18 Apr 2006

This tutorial, the first in a series on the IBM Autonomic Integrated Development

Environment (AIDE), shows how you can get up and running quickly with the IBM

AIDE toolkit. Discover touchpoint creation, modification, and deployment and learn

about the internals of the touchpoint in relation to the underlying model.

Section 1. Before you start

Learn what to expect from this tutorial and how to get the most out of it.

About this series

This tutorial is the first in a series that describes techniques for the development of

autonomic computing technology using the IBM® Autonomic Integrated

Development Environment (AIDE) toolkit. This tutorial was written as a type of

one-stop shop for new AIDE users; its goal is to get you comfortable using the AIDE

toolkit, the associated technologies, the design philosophy, and the examples that

come bundled with the toolkit.

The remaining tutorials in the series will describe touchpoint deployment on several

platforms, including Linux®, MySql, and Apache. By the end of the series, you

should have a sound understanding of the development of autonomic technology on

generic and open source platforms.

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

The major benefit of autonomic computing on these platforms is standards-based

manageability. Too many operational software systems have either proprietary point

management facilities or are essentially unmanaged. The result is that resources are

wasted because automated management procedures don't account for them. Worse

than this, many such systems are not optimized and are vulnerable to the threats of

partial or complete failure and external attacks.

The manageability requirements for autonomic computing consist of

self-configuration, self-healing, self-optimization, and self-protection -- otherwise

known as self-CHOP. This requirement set underlies the autonomic computing

philosophy that it is no longer sufficient merely to produce and deploy software and

systems; rather, these entities must now be augmented with standard open

management capabilities above and beyond what can be achieved with proprietary

instrumentation. The IBM vision for such management capability consists in large

part of the touchpoint concept -- a relatively thin layer of software that interacts with

a managed resource to facilitate the requirements of automatic management.

This series is for anyone who knows a bit of programming and who wants to better

understand the growing need for manageable systems and software. The series'

intention is to help autonomic computing programmers to become as productive as

possible as quickly as possible. With this in mind, the tutorial openly discusses any

problems encountered using the software and provides workarounds and solutions -things

you can't get from the Help file!

About this tutorial

This tutorial describes how to get started with the AIDE toolkit and takes you from

the point of installing and starting to use the toolkit to creating a complete touchpoint.

In moving beyond the early stages of using the technology, you learn how to use

and modify the touchpoint examples that are bundled with the package.

For this introductory tutorial, the platform is generic: Any platform that supports the

Eclipse and AIDE toolkit pair. For example, Microsoft® Windows® XP is more than

adequate.

In this tutorial, you learn how to use the AIDE toolkit to create a fully functional

autonomic computing touchpoint. In addition, you learn how to modify and test

touchpoint code.

Prerequisites

This tutorial is written for programmers with a reasonable knowledge of Java

programming, Eclipse, and system management. The ability to use an integrated

development environment (IDE) such as Eclipse and the various tools and plug-ins

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

that go with it is helpful but not necessary. Likewise, a basic understanding of the

following is useful:

• SOAP

• Web Services Addressing (WS-Addressing)

• Web Services Distributed Management (WSDM)

System requirements

To run the examples in this tutorial, the minimum platform requirements are a

computer running Windows XP on which you've installed the AIDE software and

Apache Tomcat V5.

Note: You can use Apache Tomcat V4, but you must use the compatibility package,

as well.

Section 2. Getting started

AIDE is an Eclipse-based integrated development environment for the creation and

maintenance of autonomic computing touchpoints. AIDE accommodates the needs

of architects and programmers alike with full support for modeling as well as code

generation. Touchpoints can also be deployed onto a range of application servers.

To start using AIDE quickly, use Tomcat V5. If you don't want to update your Java

software development kit (JDK) or your IBM Java Runtime Environment (JRE), the

Apache Tomcat V4 compatibility package is available for download from the Apache

Tomcat home page.

Install AIDE

Installing AIDE is similar to installing other Eclipse plug-ins, although there isn't really

an installation program as such. The AIDE zip file contains two folders -- one named

Features and another named Plugins. Copy the contents of the Features folder into

the Features folder of your Eclipse installation (ECLIPSE_HOME/features or, on a

computer running Windows, %ECLIPSE_HOME%/features). Similarly, copy the

contents of the Plugins folder into the Plugins folder of your Eclipse installation

($ECLIPSE_HOME/plugins or, for Windows, %ECLIPSE_HOME%/plugins).

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

Restart Eclipse. The plug-ins are loaded; you should see the AIDE

help/cheatsheets/docs folder in the Help > Help Contents menu. These help

documents include the overview of WS-RF/WSDM/AC, the run-time environment,

tooling basics, examples, and so on.

Gotchas and pitfalls

The name of the installation folder into which you install the toolkit should be

something short, such as C:\MyApps. I experienced problems getting the sample

touchpoints to work when I had long paths and folder names with embedded spaces.

I reinstalled the toolkit and these problems went away. So keep it simple!

After you start using AIDE, keep a close eye on the Eclipse console window for any

error messages. The toolkit generates a lot of informational messages interspersed

with occasional error messages (for example, if something isn't working properly).

Section 3. Building your first touchpoint

The steps to create a project and a basic touchpoint are described in some detail in

the AIDE online help files. The purpose of this tutorial is to get you up and running

quickly, so I will briefly describe the main steps required to create the basic

touchpoint and make it operational without your having to refer to the help.

Note: It can be a bit cumbersome trying to view the online help while running the

various wizards. If you need to access the help often, consider printing the relevant

pages before running the wizards.

Create a Manageability Endpoint Project

Now that you've installed all the required software, open the Eclipse workbench.

Create a new Manageability Endpoint Project by completing the following steps:

1. Click File > New > Autonomic Integrated Development Environment.

2. Select Manageability Endpoint Project and then click Next.

3. Type the project name PlatformProject.

4. Click Finish.

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

You have a container for the manageability endpoint; now you must fill it. Start by

creating the touchpoint type.

Create the touchpoint type

From the Eclipse workbench, complete the following steps:

1. Click File > New > Autonomic Integrated Development Environment.

2. Select Touchpoint Type and then click Next.

3. Type http://tempuri.org/PlatformProject for the touchpoint

type name.

4. Click Finish to include the bare minimum in the touchpoint type.

If you prefer, you can configure the default name space from the Manageability

Endpoint Builder properties. To do so, complete the following steps:

1. Click Window > Preferences.

2. In the Preferences window, expand Autonomic Integrated Development

Environment, then select Manageability Endpoint Builder.

3. Type the default namespace you want to use (for example,

http://ibm.com).

Create the touchpoint capability

From the Eclipse workbench, complete the following steps:

1. Click File > New > Autonomic Integrated Development Environment.

2. Select Touchpoint Capability.

3. Click Next to create an empty capability, then click Next again.

4. Type http://tempuri.org/PlatformProject for the name space.

5. Click Finish.

With the touchpoint capability set up, create the touchpoint implementation

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

definition.

Create the touchpoint implementation definition

From the Eclipse workbench, complete the following steps:

1. Click File > New > Autonomic Integrated Development Environment.

2. Select Touchpoint Implementation, then click Next.

3. Click Finish.

You've finished with the creation wizards for this touchpoint. Now, you're ready to

generate the Java code and the associated utilities. Your touchpoint model is nearly

complete.

Section 4. Working with the touchpoint

Learn how to generate and run your touchpoint.

Generate the touchpoint

From the Eclipse workbench, complete the following steps to generate the

touchpoint implementation definition:

1. Right-click the Touchpoint Implementation definition, then click Generate

Touchpoint to launch the Generate Touchpoint Implementation Wizard.

2. Click Add Touchpoint Type.

3. Add the touchpoint type you created in the section on creating the

touchpoint type.

4. Click Finish.

Clicking Finish initiates the automatic code-generation process, after which you

should see new files and folders in the workspace pane, shown in Figure 1.

Figure 1. The generated files

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

Note the separation between the model and the generated code. These two entities

exist independently of one another, which facilitates the use of model-driven

development and allows for separate ownership of the model and its associated

instantiation (in code). So, architects and designers can control and own the model,

while programmers are responsible for the code and any associated customizations.

This arrangement accommodates the emerging trend toward architecture-driven

software development.

Another powerful aspect of AIDE is its substantial use of wizard technology. As with

any use of wizards, this behavior facilitates efficient and accurate design and

development workflows. It's likely that future versions of AIDE will extend this

function to make the process of touchpoint generation increasingly automated.

Run the touchpoint

You're ready to run the touchpoint on Apache Tomcat (or whichever Web container

you choose). From the Eclipse workbench, complete the following steps:

1. Open a command prompt and run deploy.bat in the

WebContent\WEB-INF folder.

2. Right-click the project, then click Run As > Run on Server.

If Apache Tomcat isn't running, step 2 starts the server for you after you register the

required server. This process launches the Run On Server wizard, shown in Figure

2.

Figure 2. The Run On Server wizard

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

Click Finish to run the touchpoint on the Apache Tomcat server. If everything is

correctly installed, you should see something like Figure 3.

Figure 3. The finished touchpoint

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

You have your autonomic launch pad. Now, look at the touchpoint.

Section 5. The touchpoint schema

Learn how to create the touchpoint schema and avoid common touchpoint-related

pitfalls.

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

Create and browse the touchpoint schema

Start by clicking Create & browse to display the schema and the allowed

operations. The Create link contacts a software factory that in turn creates a new

instance of the manageability endpoint. It also displays the property values of the

endpoint in a table and provides form controls for manipulating the endpoint. This is

a basic manager.

Problem: Touchpoint non-deployment

If you forget to deploy the touchpoint on Apache Tomcat, you might see the

exception shown in Figure 4.

Figure 4. An exception

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

This problem is easily fixed. Simply follow the steps outlined in the section on

running the touchpoint to run deploy.bat. After the touchpoint has been successfully

deployed, you should be able to click Create & browse or View WSDL without

exceptions occurring.

Problem: Running multiple instances of Apache Tomcat

Occasionally, you might encounter the error message shown in Figure 5.

Figure 5. Trying to run Tomcat twice

Test in your browser

If you want to test the touchpoint outside Eclipse, point your browser

to http://localhost:8080/PlatformProject. You should see the same

window as shown in Figure 3 during the Eclipse test. You can carry

out the same schema examination and operations steps as above

using your browser.

Again, this problem is easily fixed. Identify the running instance of Tomcat, stop it,

and then retry. If for some reason Eclipse itself is running Tomcat yet you can't run

your touchpoint, restart Eclipse to fix the problem.

Undeploying the touchpoint

When you're finished with the touchpoint, you can "undeploy" it by opening a

command prompt and running undeploy.bat in the WebContent\WEB-INF folder (the

same folder that contains deploy.bat).

Section 6. Model-driven development

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

The steps you've taken to create a touchpoint are, in fact, steps to create a model.

The elements of this model consist of:

• Touchpoint types

• Touchpoint capabilities

• Touchpoint implementation guidelines

The AIDE toolkit comes bundled with three examples of preconfigured touchpoints:

• Apache Derby Database example

• WeatherStation example

• Generic Log Adapter (GLA) Touchpoint example

I discuss the WeatherStation example later, but you can extract, import, and build

these models yourself by following the steps described in the online help.

When you generate code, you are in a sense instantiating the model for an

execution environment. The touchpoint is an abstraction for a managed resource.

Using the WeatherStation example that comes bundled with AIDE, the associated

model entities appear in Figure 6.

Figure 6. The WeatherStation touchpoint model elements

You employ this model to create an executable touchpoint that matches your

management system environment. In other words, your management system can

execute the touchpoint and use it to acquire data from and control the operation of

the underlying managed resource.

Gotchas and pitfalls

The many steps and wizard interactions associated with model-driven development

can seem a bit of a drag at first. Don't despair: It's worth pursuing, because this is

increasingly how software is being produced. If you need more information on this

subject, the online Help has many excellent articles and worked examples on the

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

Eclipse Modeling Framework (EMF), Service Data Objects (SDO), and so on. These

are well worth reading in their own right as well because of the light they shed on the

approach IBM is taking on touchpoint technology.

Change touchpoint parts

As mentioned earlier, AIDE uses Eclipse-based model facilities (called the Eclipse

Modeling Framework) to generate the touchpoint. The online Help includes details

about the way AIDE uses the EMF.

In this section, I use the WeatherStation example touchpoint packaged with the

AIDE toolkit. The help files provide detailed directions for building and deploying this

example. Following these directions and the above steps, you will be able to run the

touchpoint as shown in Figure 7.

Figure 7. The WeatherStation touchpoint

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

Experiment with this touchpoint, clicking the various buttons and observing the

resulting operations and any associated data changes. For example, clicking

Kickme() to reload the schema data executes Java code; you should see some text

fly past in the console window. Scroll up the console window to reveal the text from

the Kickme() method, which is "I've been kicked!" You modify this text in the next

section so that you can see how relatively easy it is to change and rebuild the

underlying generated source code.

You can also change some of the data in the schema. Try typing some text in the

Insert box -- for example, Hello World!. Click the down control to display the

schema items and select Description from the drop-down list as shown in Figure 8.

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

Figure 8. Setting data

Change the Description schema variable field by clicking Insert, which initiates

the update. Then scroll down to the Description field in the schema to see the

modified text. This is an example of what's often called a set operation -- modifying

managed data. As you can imagine, this operation can be quite sensitive in a real

system. By setting the wrong item or applying erroneous data to an item, you can

actually do damage.

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

So, an important element of allowing set messages is the associated

authentication, authorization, and auditing procedures. Many networking vendors

only allow read permission and require additional configuration of their products

before management system-originated updates can be made.

There are many reasons for this approach, not least of which is avoiding (or at least

minimizing the effect of) Denial of Service (DoS) attacks that use set messages. If

set messages aren't allowed, such messages are dropped quickly, thereby

minimizing the amount of processing.

A quick look at the generated Java code

As described in the online help, the Java source code consists of three major

sections:

• ibm: The location of the code that AIDE generated to implement your

manageability endpoint.

• proxy: The location of Java proxies for your manageability endpoint.

• tests: The location of Java tests for your manageability endpoint.

You should edit only the ibm item. The EMF allows for modifications to the .impl

classes while still allowing for future model updates. In other words, you can change

the .impl Java code now and still allow for future model updates and code

regeneration. The next section shows how the EMF meets this seemingly

contradictory requirement.

Customize the touchpoint code

If you followed the steps in the online Help regarding this project (copying the

WeatherStationImpl.java file from the extracted files into the generated project

folder), there should be a method called kickme(), which is shown in Listing 1.

Change the code displayed in bold in Listing 1.

Listing 1. A method in WeatherStationImpl.java

/**

*

* @generated NOT

*/

public void Kickme() throws

BaseFault

{ this.erratic = true;

System.out.println("I've been

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

kicked!");

}

The WeatherStationImpl.java class derives from the EMF EDataObjectImpl

class.

An important aspect of Listing 1 is the comment line: @generated NOT. This line is

a directive to the code generator to indicate that the code following the tag is user

code. If you regenerate the code, the generator detects a collision and simply

discards the generated version of the method. This behavior provides a convenient

mechanism for the peaceful co-existence of user code and generated code.

Now, change the contents of the kickme() method. Using Eclipse (or a text editor if

you prefer), complete the following steps:

1. Open WeatherStationImpl.java in the JavaSource\ibm\com\impl

folder.

2. Search for the text, "I've been kicked," change it to Ouch, I've been

kicked!, and save the Java file.

3. Undeploy the WeatherStation touchpoint.

4. Open the WeatherStationModels project.

5. Right-click the WeatherStation.actpim file, then click Generate

Touchpoint.

6. Accept the defaults appropriate to your environment.

7. Deploy the WeatherStation touchpoint.

8. When you click Kickme(), you should see the updated text string in the

console -- namely, "Ouch, I've been kicked!"

Congratulations! In spite of taking a bit of a kicking, you've just made your first code

change to an autonomic computing touchpoint! You've also seen how to regenerate

the touchpoint from the model. This is perhaps a good point at which to dig deeper

and describe some of the key principles of information technology (IT) management.

First however, let's see how to return your project to its unchanged state.

Revert to the unchanged project

It's easy enough to get back to the original project state. Even though you've made a

trivial change (in this case), you need to know how to get back to square one,

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

especially if you make changes that you later want to remove. To revert to the

unchanged project, complete the following steps:

1. Undeploy the touchpoint from Apache Tomcat.

2. Stop the instance of Apache Tomcat running in the Eclipse workbench.

3. Remove the touchpoint from Apache Tomcat as shown in Figure 9.

Figure 9. Deleting the Tomcat touchpoint instance

4. Close any editors that have files open belonging to the project.

5. Right-click the generated project, then click Delete.

6. When prompted to select the contents, click Delete all.

7. Restart the Eclipse workbench.

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

8. Regenerate the touchpoint.

Note that this procedure removes any user code changes, so make sure that you

save any modified files that you want to keep. You should now be back to a clean,

freshly generated project. Now, of course, you must redeploy the project on Apache

Tomcat and re-register a Tomcat instance.

Gets, sets, and events

By its nature, IT management is a problem of distributed computing. A manager

entity typically resides at location x and the managed entity (or entities) resides at

location y. So, for management to occur, you must get data from x to y and back

again. Traditionally, this problem has been solved using a simple model that allows

managed data (on the managed entity) to be:

Gets

• Updated (through set operations)

• Retrieved (through get operations)

• Notified to the manager (through event operations)

So far in this tutorial, you've seen get and set operations. A get operation is

equivalent to reading data from the managed entity or device or a proxy entity.

In network management, the operation that corresponds to a read is called polling.

In this procedure, the manager explicitly selects a given device or software entity

and requests data from it. The remote device or software entity receives the request,

gathers the required data (if it can), and sends a response message back to the

manager. If such messages are security-enabled, the managed entity may have

more work to do in authenticating and authorizing the operation.

Needless to say, polling can be an expensive operation on large networks. On a

more subtle level, polling can also consume considerable resources on the managed

entity -- for example, if tables need to be traversed or large numbers of complex

values must be computed.

Sets

A set operation amounts to a modification of data on the entity or device. The scope

for performing set operations is quite wide, ranging from modifying the

administrative status of a network port to disabling packet forwarding.

Another common use for set operations is to initiate long-running operations, such

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

as FTP file transfers. The latter can occur when it's required to update firmware on a

given device or when backing up the configuration of a network device.

Events

So, what happens when an important data change occurs on the managed entity?

Often, such changes can be significant -- for example, a partial hardware failure, an

unexpected temperature rise, or the onset of congestion on a given port. How does

the managed entity tell the manager? The answer lies in the use of events or

notifications. The next tutorial in this series provides more details on this key topic.

Section 7. Summary

This tutorial introduced you to the IBM AIDE toolkit. You should now be equipped

with a general appreciation of this Eclipse-based environment. No software system

is perfect and I've attempted to describe and provide workarounds for potential

stumbling blocks.

An important element of management system technology is a basic description of

the general philosophy of this important field. You saw some details on this

philosophy throughout this tutorial, including examples of get and set operations.

You also saw how to make minor changes to the generated code. As the series

progresses, I'll expand on this coverage, showing you how to build touchpoints for

Linux, MySql, and Apache.

Building a touchpoint Trademarks

developerWorks® ibm.com/developerWorks

Resources

Learn

• New to Autonomic computing: A guide to introduce you to autonomic

computing.

• "Simulate autonomic resources in your IT system" (developerWorks, April

2005): This tutorial demonstrates how to simulate autonomic resources using

the IBM Manageability Endpoint Simulator.

• The autonomic computing edge: Keeping in touch with touchpoints

(developerWorks, August 2005): This Edge article describes what a touchpoint

is, how touchpoints encapsulate managed resources, and some things to

consider when designing touchpoints.

• developerWorks technical events and webcasts: Stay current with

developerWorks technical events and Webcasts.

• developerWorks autonomic computing zone: Stay up to date on the latest

developments and technology in autonomic computing with the developerWorks

autonomic computing zone.

Get products and technologies

• Autonomic Computing Toolkit: The Toolkit is a collection of IBM self-managing

autonomic computing technology components, tools, scenarios, and

documentation designed for users wanting to learn, adapt, and develop

autonomic behavior in their products and systems.

• IBM Autonomic Integrated Development Environment (AIDE): A set of software

development tools that embrace the Web Services Distributed Management

(WSDM) standard. Includes tools such as the IBM Manageability Endpoint

Builder (for building endpoints that allow products to expose manageability

interfaces) and the IBM Manageability Endpoint Simulator (previously known as

IBM Touchpoint Simulator).

• IBM trial products for download: Build your next development project with IBM

trial software, available for download directly from developerWorks.

Discuss

• developerWorks blogs: Participate in developerWorks blogs and get involved in

the developerWorks community.

• Join the discussion: Drop in on the "Autonomic computing: an insider's

perspective" discussion forum.

Building a touchpoint Trademarks

ibm.com/developerWorks developerWorks®

About the author

Stephen B. Morris

Stephen is the CTO of Omey Communications in Ireland. For the past

20 years, Stephen has worked for some of the world's largest

networking companies on a wide range of software projects, including

J2EE/J2SE-based network management systems, billing applications,

porting and developing SNMP entities, network device technologies,

and GSM mobile networking applications. He is the author of Network

Management, MIBs and MPLS: Principles, Design and Implementation

(Prentice Hall PTR, 2003) as well as several articles on network

management and other topics for InformIT and OnJava.com. You can

reach Stephen at stephenbjm@yahoo.com.

Building a touchpoint Trademarks

Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM

Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM ... View more Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM

Delete template?

Save as template ?

Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM Hit the ground running with AIDE, Part 1: Building a touchpoint - IBM