Running the Sample Code in This Book | Microsoft .NET and J2EE Interoperability Toolkit (Pro-Developer)

Many chapters in the book contain sample code. All the samples referenced in the text are also included on the CD that accompanies the book. The requirements for running the samples are as follows .

Operating Systems

I've assumed that you'll use a Windows operating system to run the code samples in this book, ideally either Microsoft Windows XP or Microsoft Windows 2003. For certain server-specific samples, Microsoft Windows 2003 will be required.

.NET Environment

All the .NET code samples are written to work on version 1.1 of the Microsoft .NET Framework (v1.1.4322). The Microsoft .NET download site (found at http://www.microsoft.com/net ) offers two download options: the .NET Framework Redistributable or the .NET Framework SDK.

If you plan to use Visual Studio .NET, the .NET Framework SDK is automatically installed as part of the product and will not require downloading separately. If you do not plan to use the IDE, you should download and install the .NET Framework SDK. The SDK contains a number of command-line utilities that will be used throughout many of the chapters.

Many of the code samples also require ASP.NET. Although Web pages and controls are not shown in every chapter, the underlying mechanisms to host Web services rely on ASP.NET. Before running any of these samples, you need to ensure that IIS and ASP.NET are both correctly installed and that security is correctly configured. The next three sections will take you through this process.

Installing ASP.NET on Windows Server 2003

Windows Server 2003 allows servers running the operating system to be assigned roles. For example, certain servers within a data center could be designated as File and Print servers, whereas others could be designated as Web or Application servers. Servers are installed with different software components based on their assigned role.

To allow many of the samples found within this book to work correctly with Windows Server 2003, you'll need to configure the server to have the role of an application server. Configuring the server for this role will install the required software (FrontPage Server Extensions and ASP.NET) for the samples.

To assign the role of your server, open the Configure Your Server Wizard. This wizard can be launched by selecting it from the Start\Program Files\Administrative Tools menu. After the wizard is launched and detects your network settings, a list of available roles will be displayed, as shown in Figure 1.1.

Figure 1.1: Configuring the Server Role in Windows Server 2003.

Select the Application Server role as highlighted in the figure, and click the Next button. As displayed in Figure 1.2, check both the FrontPage Server Extensions option and the Enable ASP.NET option. ASP.NET is used to serve all the .NET Web services that are shown in this book. FrontPage Server Extensions is used to provide access to Web sites from a number of Microsoft applications, including Visual Studio .NET 2003.

Figure 1.2: Enabling FrontPage Server Extensions and ASP.NET in Windows Server 2003.

Click the Next button to confirm these choices, and complete the wizard to install the necessary components. During this installation, you might be prompted for the Windows Server 2003 CD or network location.

Installing ASP.NET on Windows XP Professional

Installation of ASP.NET for Windows XP Professional is done using the Add Or Remove Programs control panel. Within the control panel, select Add/Remove Windows Components and ensure that Internet Information Services is installed. (The common files and FrontPage extensions are required.) Installing the Microsoft .NET Framework SDK will include all the required ASP.NET options.

Configuring ASP.NET Security

Some of the ASP.NET samples that will be demonstrated write to the event log, which requires additional privileges not normally required by applications that use ASP.NET. To enable these samples to work correctly, you'll need to adjust the ASP.NET security settings.

Warning

Changing the ASP.NET security settings could provide rogue programs with the ability to access and alter nearly all resources on the computer. It is highly recommended that these modifications be done only for the purposes of running this book's sample code and that you consult the following articles to correctly set up the security of a deployed application: http://www.microsoft.com/technet/treeview/default.asp?url=/ technet/prodtechnol/windowsserver2003/ proddocs/server/aaconprocessmodelelement.asp and http://www.microsoft.com/technet/treeview/default.asp?url=/technet/ prodtechnol/windowsserver2003/proddocs/server/ aaconconfiguringaspnetprocessidentity.asp .

For the security settings, we are going to adjust the ASPNET account (that is, the account the ASP.NET process uses) to run under the context of the local system account. These instructions apply to both Windows Server 2003 and Windows XP Professional.

To do this, edit the machine.config file in the C:\Windows\Microsoft.NET\Framework\v1.1.4322\CONFIG directory. This directory might be different depending on your exact installation setup of Microsoft Windows. Within this file, search for a section called processModel . The section should start like this:

 <processModel     enable="true"     timeout="Infinite"     idleTimeout="Infinite"     shutdownTimeout="0:00:05"      requestLimit="Infinite"      requestQueueLimit="5000"      restartQueueLimit="10"     memoryLimit="60"

Change the userName attribute to SYSTEM :

 userName="SYSTEM"

Also, ensure that the password is set to AutoGenerate . Save and close the file.

For Windows 2003 only, one additional step is required. The same configuration change needs to be made to the application pool. Launch Internet Information Services Manager from the Start/Programs/Administrative Tools menu. Expand the Application Pools tree, and right-click the DefaultAppPool. Select Properties, and click the Identity tab. Set the security account for this pool as Predefined and Local System. Confirm the security warning, and close the dialog box.

After you have made these security adjustments, launch a command prompt window and type iisreset . This will stop and start the IIS services to ensure that the adjusted security configuration is applied.

Java/J2EE Environment

This book does not include a version of the JVM with the sample code on the companion CD. Nor does it include a version of any J2EE application server. The intent was to ensure that all the code samples are as vendor neutral and application server neutral as possible because it would be impossible to anticipate which environment each reader of the book would use.

For testing purposes, the scripts supplied with the samples are configured to deploy the sample code to a local instance of JBoss version 3.0.7. As mentioned previously, JBoss is an open-source J2EE application server that can be downloaded from http://www.jboss.org . When downloading, make sure that you select the version that includes JBossWeb.

All code samples have been written for and tested against a JVM based on the Java 2 SDK 1.4.1 specification and the J2EE 1.3 specification.

Microsoft Products

The following Microsoft products are referenced in the code samples throughout the book.

Microsoft SQL Server 2000

Chapter 7, "Creating a Shared Database," Chapter 11, "Asynchronous Interoperability, Part 4: BizTalk Server," and Chapter 12, "Presentation Tier Interoperability," all make use of Microsoft SQL Server 2000 to cover certain interoperability elements. Although using most vendor databases with these samples is entirely possible, the drivers referenced and some of the stored procedures written are specific to SQL Server.

Downloading an evaluation

Microsoft SQL Server 2000 is not included on the accompanying sample code CD. If you do not currently have an instance of SQL Server that can be used for these samples, you might want to take a look at http://www.microsoft.com/sql . At the time of this writing, a 120-day trial version of SQL Server 2000 can be downloaded from http://www.microsoft.com/sql/evaluation/trial/ .

Microsoft SQL Server 2000 Driver for JDBC

To allow connectivity to Microsoft SQL Server 2000 from the Java environment, we'll be using the Microsoft SQL Server 2000 Driver for JDBC. This driver allows the Java Clients in the samples to access an instance of SQL Server 2000, and it's used in Chapter 7 and Chapter 12.

Downloading

The Microsoft SQL Server 2000 Driver for JDBC can be downloaded from the Microsoft SQL Server MSDN downloads at http:// msdn.microsoft.com/downloads/list/sqlserver.asp . The sample code that uses this JDBC driver has been tested with the SP1 (Service Pack 1) release.

Microsoft Host Integration Server 2000

Chapter 10, "Asynchronous Interoperability, Part 3: Bridging with Host Integration Server," shows how components within Microsoft Host Integration Server can be used to bridge Microsoft MSMQ and the IBM WebSphere MQ product.

Downloading an evaluation

Microsoft Host Integration Server 2000 is not included on the sample code CD. Product information and licensing is available from http://www.microsoft.com/hiserver . If you do not already have Microsoft Host Integration Server 2000, a 120-day trial can be downloaded from http://www.microsoft.com/hiserver/evaluation/trial/default.asp.

Microsoft BizTalk Server 2004 Beta 1

To utilize a broker-based solution, as described in Chapter 11, we'll use a prerelease copy of Microsoft BizTalk Server 2004. BizTalk Server includes many features that include message transformation, support for legacy adapters, and orchestration. Running the sample code in Chapter 11 will require Visual Studio .NET 2003.

Downloading the beta

At the time of this writing, Beta 1 is going through release. To download the latest trial edition of the software, go to http://www.microsoft.com/biztalk/evaluation/trial/default.asp . Although the sample code in this book is based upon Beta 1 code, you should always use the latest version of the product.

Microsoft Web Services Enhancements 1.0

We'll use Microsoft Web Services Enhancements (WSE) 1.0 for the advanced interoperability samples in Part IV of this book. WSE 1.0 provides a number of libraries to extend the functionality of the Web Services classes in .NET, based on the new specifications.

Downloading

WSE 1.0 is a free download from MSDN and can be found at http://www.microsoft.com/ webservices . In addition to downloading this version, installation of SP1 (Service Pack 1) from the same location is highly recommended.

Third-Party Products

It would be impossible to write a book on interoperability between the .NET and Java platforms without using resources from third-party companies because so many connectors and implementations we'll be working with aren't part of either framework. The following third-party products, some of which are included on the companion CD, are referenced in the book.

TME GLUE 4.0.1 and Electric XML

Chapter 3, "Exchanging Data Between .NET and Java," looks at data exchange between .NET and J2EE. One fundamental demonstration of this exchange uses XML serialization to pass data between the two platforms as XML documents.

To achieve XML serialization for the Java sample code, we'll use the XML classes that are available from a third party known as The Mind Electric (TME) and can be found at http://www.themindelectric.com . This implementation, known as TME Electric XML and which is part of the TME GLUE 4.0.1 product, was found the most compatible with the samples presented in this book.

As we'll discuss in Chapter 5, Web services today are more of a vendor- specific approach than an integral part of the current J2SE and J2EE specifications. As a result, to develop Web services for the Java platform, you must choose a third-party implementation.

As with the classes we'll use later in the book to demonstrate XML serialization, I've chosen to standardize on GLUE, also from The Mind Electric. I'll discuss my reasoning behind this selection and offer an objective look at the Web services standards in the Java platform in Chapter 5.

What Is The Mind Electric?

The Mind Electric (TME) is a leading pioneer and provider of Web Services Infrastructure Solutions. TME's mission is to fundamentally simplify the creation, deployment, management, and orchestration of next-generation distributed applications. Its first product, TME GLUE, is the leading independent Java Web Services platform and has been branded the "Turbo Pascal of Web Services" by Forrester Research. The company's second product, TME GLUE Web Services Fabric (code-named GAIA), is intended for enterprises that wish to deploy production-grade service- oriented architectures (SOA) and provides critical features such as service registration, dynamic discovery, management, failover, distributed security, and XML message processing.

TME GLUE Web Services Fabric plugs natively into any .NET or J2EE server or can be hosted standalone. Its decentralized architecture provides scalability and reliability; servers self-assemble using their unique GAIA technology to form a smart Web services fabric that self-heals if servers become temporarily disconnected. The more servers that are added, the more powerful the fabric becomes.

Licensing

Although TME GLUE 4.0.1 is installed with the sample code, you will need to download an evaluation license from The Mind Electric. For using the sample code within this book, a license is available that will allow all the features to be used within a 60-minute period. A license can be downloaded from http://www.themindelectric.com/books . From this link, select the option for this book, and a license file will be sent to you via e-mail.

Once it is received, install the license file by copying it to the C:\Interoperability\Tools\Glue\lib directory. Using a command prompt, navigate to this directory and run the following command to add the license file to the libraries:

 jar uvf glue-all.jar glue-license.xml

Additional information about installing the license and more options for the commercial product can be found at http://www.themindelectric.com .

Intrinsyc Ja.NET 1.4

Microsoft does not create an implementation of .NET Remoting for Java, which is discussed in Chapter 4, "Connectivity with .NET Remoting." However, the specification is available, and as a result, a number of third-party implementations have begun to appear. The implementation used for the samples in Chapter 4 and Chapter 7 is Intrinsyc Ja.NET, which is installed with the sample code.

What Is Intrinsyc?

Intrinsyc ( http://www.intrinsyc.com ) is a global leader in providing unique, cost-effective software and hardware solutions that enable companies to create, network, and manage a wide range of specialized, intelligent devices. Intrinsyc's products and services include its flagship Ja.NET enterprise application integration product, through which the .NET Framework can seamlessly interoperate with the Java and J2EE platforms.

Licensing

At the time of this writing, Intrinsyc Ja.NET provided the best implementation for the samples for using the .NET Remoting stack with Java that I wanted to show in this book. Not only does the product support the .NET Remoting stack, but it also supports enterprise application technology on both .NET and J2EE. For example, Ja.NET calls components hosted as EJBs or through Component Services.

As with GLUE 4.0.1, although Ja.NET is installed as part of the sample code, a separate license file has to be requested from Intrinsyc. To request this file, go to http://support.intrinsyc.com/book/ and supply your name, e-mail address, and company name in order to request a license. Once you receive the license e-mail, copy the janet_license.xml file attachment to the C:\Interoperability\Tools\Ja.NET\lib directory. Configuration of the license is performed when the tools are run and will be covered with the sample code shown in Chapter 5.

IBM WebSphere MQ

In Chapter 9, "Asynchronous Interoperability, Part 2: WebSphere MQ," and Chapter 10, we'll look at using a Message Queue to achieve interoperability at the resource tier. IBM WebSphere MQ (formerly known as MQ Series) has been adopted by many enterprises. Throughout Part III, "Interoperability Technologies: Resource Tier," we'll show code examples that use both WebSphere MQ and Microsoft Message Queuing (MSMQ).

Downloading an evaluation

IBM WebSphere MQ is not supplied on the accompanying CD. For those who do not own the product but who want to run the sample code, a 90-day evaluation version is available at http://www.ibm.com/mqseries .

Installing the Sample Code

Install the sample code from the accompanying CD, which will auto-run when inserted. All the code examples and the required third-party libraries (described earlier) are installed in a C:\Interoperability directory. Although this can be changed during setup, to simplify the process of following along with the samples as you read the book, it is recommended you accept the default location for this directory.

Make sure that the Microsoft .NET Framework 1.1 is present prior to installing the sample code. Doing this, and rebooting after the sample code has been installed, will ensure a correct installation.

Building and Running the Sample Code

Everyone has a different setup and environment, and if the sample code does not run, it's difficult from where I sit to predict where the errors might lie. However, I can offer several tips that might help you get all the samples working.

Building the Source with Ant and NAnt

Ant is one of the common build tools used for deploying applications in the J2EE environment. Its popularity is largely due to the way it can be extended with XML files and calls to regular Java classes to perform complex builds. With each sample in this book, I've included an appropriate build.xml file that can be used with Ant 1.5.1 or later to compile. Obviously, the Java source also can be loaded and compiled in an IDE.

I have chosen the .NET equivalent of Ant (known as NAnt) for building the .NET samples that are to be run from the command line. For each sample, a default.build file contains the build instructions for NAnt 0.7.9 or later.

The Ant and NAnt build tools are installed automatically with the sample code. For more information about the build tools, consult http://ant.apache.org and http://nant. sourceforge .net .

Common Script Functions

Launching Ant or NAnt from the command line is performed by typing ant or nant from within the directory that contains the build file. By default, using these commands without any parameters will compile the source code in that directory. In a number of the samples, the following parameters can be used to specify targets within the build files for certain operations:

ant clean or nant clean is typically used to remove the compiled classes associated with a build.
ant run or nant run can be used with samples that can be executed directly from the command line. These are normally samples that do not require any additional infrastructure or deployment to run.
ant package is used for J2EE samples that require building into a J2EE package. For example, this could include the creation of a JAR, WAR, or EAR file that is to be deployed to a J2EE application server.
ant deploy is used for J2EE samples that require deployment to a J2EE application server; it performs the copy from the source directory to the application server. In the samples, this deploy script is configured to deploy to a local instance of JBoss 3.0.7.
ant undeploy is used to remove a deployment from a J2EE application server.

Configuration Directory

Many of the samples and build scripts rely on information from other software installations for proper execution. For example, building the sample code for the WebSphere MQ client requires access to the JAR files that are supplied with the WebSphere MQ product. Because it's not possible to second-guess where these files might be located on your machine, properties files are used by both the Ant and NAnt scripts to determine these file locations.

These property files can be found in the C:\Interoperability\Samples\Config directory. For example, the settings to indicate where the WebSphere MQ libraries are located can be found in the webspheremq.properties file. Properties files are also used by some of the NAnt scripts. It's important to make necessary adjustments to these property files to reflect your own configuration. This will ensure that the build process of the sample code is successful.

Running the Code on Multiple Machines

The majority of the code samples have been designed to run on a single machine. Doing so allows you to fully examine the processes and messages that are passed between the .NET and J2EE environments without the complications of adding networking issues. It's fair to say that because teaching you to achieve interoperability is the goal of this book, the book's code examples will work perfectly well when distributed to a number of machines. Doing so, however, might require some slight modifications of configuration files to reference multiple machines on the network instead of just referencing the local machine. These modifications will be referenced where necessary.

All the samples in the book assume that IIS is configured for localhost on port 80 and that J2EE Web applications (regardless of the server or vendor) run on port 8080 on the same machine. When you run the code samples while following this book, I recommend using these configurations. Once they are working, you can change these settings and the appropriate configuration files as required.

Setting Environment Variables

Because many of the code samples can be run from the command line, you must ensure that you've correctly set the environment variables. On a machine running the Windows operating system, you can specify this configuration in the System control panel, under the Advanced tab. The recommendations are as follows:

C# sample code

Ensure that the System Path contains an entry to the directory containing the C# compiler (CSC.EXE). This compiler is normally found in the C:\WINDOWS\Microsoft.NET\Framework\v1.1.4322 directory for v1.1 of the .NET Framework.
Ensure that the System Path also contains an entry for the bin directory of the NAnt installation (for example, C:\Interoperability\Tools\NAnt\bin). This will allow the NAnt executable to be run from the command line.
Ensure that the System Path contains an entry for the bin directory of the Framework SDK. This will allow many of the command-line tools to be run from a command prompt. If you have installed Visual Studio .NET 2003 in the default location, this should be C:\Program Files\Microsoft Visual Studio .NET 2003\SDK\v1.1\Bin. If you are using the .NET Framework SDK 1.1 alone, this will be C:\Program Files\Microsoft.NET\FrameworkSDK\Bin.

Java sample code

Ensure that the System Path contains an entry to the directory containing the Java compiler (JAVAC.EXE) and the executable to run Java applications (JAVA.EXE). These two programs are located in the bin directory of the J2SE SDK.
Ensure that the System Path also contains an entry for the bin directory of the Ant installation (for example, C:\Interoperability\Tools\Ant\bin). This will allow the Ant executable to be run from the command line.
Set the JAVA_HOME environment variable to the root of the J2SE SDK installation. This is normally performed with the installation of the J2SE SDK, and is required by Ant.
Ensure that the CLASSPATH environment variable contains an entry to % JAVA_HOME %\lib\tools.jar, where % JAVA_HOME % is the previous environment variable.
The CLASSPATH environment variable should also be modified to include the required JAR files for the sample code to compile and run. This is especially important when running sample code that includes code for third-party tools, such as Ja.NET and GLUE. A number of these JAR files will be added to the default path by the sample code installer. It is worth double-checking these values before compiling any of the samples.

Running the Setup Validation Tool

As the majority of the examples shown within this book contain dependencies on numerous installations, environment variables, and other settings, the sample code also ships with a setup validation tool. This tool can be used to verify which products have been installed and configured, and potentially highlight any problems that may prevent the samples from running correctly.

The tool, called SETUPVALIDATOR.EXE, can be found in the C:\Interoperability\Tools\Setup directory. Running the tool from the command line will display potential problems and also record these to a SetupValidator.log file in the same directory. In the case where problems are found, the tool will offer suggestions or recommendations to allow them to be corrected.