Port the Personal Web Site Starter Kit to Tomcat

Using Grasshopper, you can take this reference application from Microsoft^® and in just a few minutes run it on a Java^™ EE application server, such as Apache Tomcat, under Linux^®.

How to get it

Download Grasshopper 2.5, run the executable file, and follow the installation instructions. You can install this side-by-side on a machine that has Grasshopper version 2.x installed.

Please note the following system prerequisites:

• Operating System: Windows XP SP2/SP3, Windows 2003 Server, or Windows Vista Ultimate or Business

  Note:

  In order to work with Grasshopper on Windows Vista, you must launch the Visual Studio IDE from an administrator command prompt and launch Tomcat application server as an administrator.

• Visual Studio .NET 2008, Standard or Professional editions, including the Visual Web designer component

Getting Started with Visual Studio, .NET 2.0, and Grasshopper

	Figure 1. New Project dialog		Figure 2. Visual Studio workspace

Once you've installed Grasshopper, launch the Visual Studio IDE.

Then, choose New Project from the File menu, and the New Project dialog appears (Figure 1).

Check out the project types on the left of this dialog, and you'll see Visual Basic for Java EE and Visual C# for Java EE as supported project types. From here, you can select new project types such as an ASP.NET Web application. Grasshopper supports Web applications, Web services, server controls, console applications, and class libraries.

Once you've created your Web application, you'll see the familiar Visual Studio workspace, which you can use to design your Web Form applications as you typically would. (See Figure 2.)

The application shown in Figure 2 is a simple Hello one. Use the Visual Studio Toolbox to drag a TextBox control, a Button control, and a Label control onto the Default.aspx design surface. You may use the split view editing of the Web designer to see the Source editor as well as the Design editor. This allows you to specify the code to run in order to handle the button click event. Change the function's code to read like this:

protected void Button1_Click(object sender, EventArgs e)
{
    Label1.Text = "Hello " + TextBox1.Text;
}

	Figure 3. Application running on Tomcat

When the button is pressed, the Label1 label reads "Hello " followed by whatever name is typed into the text box.

The high level of productivity you expect from the Visual Studio development environment is available to you as a cross-platform developer, including full IntelliSense, a cross-platform debugger, and an integrated help system.

Once you’ve installed Grasshopper, you'll find an entry in your Start menu, under the Mainsoft for Java EE group, that you can use to launch Tomcat. Tomcat will launch in a DOS prompt window. When it is fully loaded, you may build, run, and debug your application.

Now, press CTRL-F5 to run the application and you can see your application running on Tomcat. It's that easy! You can see this in Figure 3. Note that the application is running on port 8080.

Using the Personal Web Site Starter Kit

The Personal Web Site Starter Kit (PWS) is an application developed by Microsoft to showcase the .NET Framework 2.0 and ASP.NET 2.0 features. It is available for download from MSDN and offers a complete, ready-to-run, and customizable interactive Web site for sharing photos, resumes, and more. This application uses many of the new ASP.NET 2.0 technologies and controls including ASP.NET authentication, the LoginView control, site-based navigation, auto-generated menus, ObjectDataSource, and more.

This article shows you how to port the .NET PWS application to Java. The ported application is also available at <Mainsoft_install_dir>\Samples\{CS|VB}\Tomcat\PWS.

One example of a new ASP.NET 2.0 feature that PWS uses extensively is the concept of Master Pages. With a Master Page you design and specify the look and feel of your page and give this the .master file extension. Using the object-oriented methodology, you can then derive other pages from this master and inherit all styling and layout from the Master Page. So if, for example, you take a look at Albums.aspx, you'll see that there is a lot less markup on the page than you'd usually expect. This is because most of the markup that it uses is on the Master Page, and it inherits it because of the reference to the Master Page in the page declaration:

<%@ Page Language="C#" MasterPageFile="~/Default.master"
Title="Your Name Here | Albums" CodeFile="Albums.aspx.cs"
Inherits="Albums_aspx" %>

	Figure 4. Creating the Personal Web Site

A full discussion of the Personal Web Site Starter Kit, including a complete technology discussion can be found on MSDN at this URL: http://msdn.microsoft.com/en-us/library/ms972963.aspx.

In the next few sections, you'll see how to prepare your environment for rehosting this application on Java-enabled platforms, and then you'll go through the simple steps to rehost it.

Step 1: Use the Personal Web Site Starter Kit

Download the PWS from Microsoft at this link: http://msdn.microsoft.com/en-us/cc533486.aspx. Once you've installed it, you can create a new Personal Web Site using the template provided with the installation of Visual Studio. To do this, select File > New > Web Site, and you'll see the template for Personal Web Site Starter Kit. Select the .NET Framework 2.0. Select the Personal Web Site Starter Kit template, and specify the directory where you want the Web site to be created, and set the language to C# (Visual Basic is also supported). See Figure 4. You will be asked whether to upgrade the Web site to Framework 3.5. Answer No.The IDE will then create the Web site for you in the specified directory, and it can be run on the Cassini Web server by pressing F5. You can see it in action in Figure 5.

	Figure 5. Personal Web site running on Cassini

Step 2: Convert the Web Site into a Grasshopper Web application project

The PWS created your Web site as a Web site project where you stored all the files on the file system, without an associated project file. For Grasshopper, you'll need a project file, as this is used to handle the compiler directives to cross-compile your MSIL code into Java bytecode. Thus, you will need to convert your Web site into a Web application project.

Add a new C# for Java EE Web application project (Figure 6) to the solution, and delete its Default.aspx and Web.Config files. Then select everything from the Web site project and drag-and-drop it into the new project (Figure 7).

After Visual Studio is done inserting the files into the new project, right-click the new project and select: Convert to Web Application. Wait for Visual Studio to complete the conversion.

Now, you should be able to build the new project with no errors. In fact, you no longer need the original Web site in your solution, and you can safely remove it. After doing so, you should be left with a single project under this solution.

Step 3: Configure the application database

	Figure 8. SQL Express Protocols in Computer Management

The original .NET Web application used an in-process database, stored in the personal.mdf file, which is located in the App_Data folder.

Java applications can use the Microsoft JDBC driver to connect to SQL Server Express. However, the MS SQL Server JDBC driver does not provide a way to connect to an embedded database such as the one used by the Web site application.

In reality, due to performance, scalability and robustness considerations, real world Web applications would not typically use embedded databases. Instead, they would use a database managed by a commercial database server such as SQL Server.

Now we need to modify the ported .NET application and switch from an embedded database to an out-of-process SQL Server Express database.

Your ported application will be a 100% pure Java bytecode application at runtime and will use the Microsoft SQL Server JDBC drivers for database connectivity.

First, ensure that your SQL Server Express database is accessible via TCP/IP and that it supports mixed-mode authentication.

To do this, use the Computer Management application in the Control Panel > Administrative Tools. Find the Protocols for SQL Express entry, under Services and Applications > SQL Server Configuration Manager > SQL Server 2005 Network Configuration. It should look like Figure 8.

Make sure that TCP/IP is Enabled. You can do this by double-clicking its entry on the right-hand side of the screen, and enabling it on the Protocol tab.

The Grasshopper runtime relies on the Microsoft JDBC driver to connect to SQL Server Express and therefore requires the SQL Server authentication to be enabled on the SQL Express instance. Make sure that the SQL Express instance works in mixed-mode authentication. To do this, you can use Microsoft’s SQL Server Management Studio Express (SSMSE) tool, freely available for download from Microsoft.

Launch SSMSE, sign in, select the database and right-click. From the context menu, select Properties. You'll see the SQL Server Properties dialog. Select Security and make sure that the SQL Server and Windows Authentication mode radio button is selected (Figure 9).

	Figure 9. Set mixed-mode authentication

Now you have to restart the SQL Express server to allow the change to take effect. You may do this by right-clicking the server name and choosing the option Restart.

NOTE: If you do not restart the server, you will get an error message later on when trying to run the application.

Grasshopper runtime uses the SQL Server Browser Service to connect to SQL Server Express. To make sure that the SQL Server Browser Service is running, launch the Computer Management again, expand Services and Applications, and then click Services. In the list of services, double-click SQL Server Browser, and in the SQL Server Browser Properties window, click Start.

You are now ready to run an initialization script that attaches the sample's Personal.mdf database file to your running instance of SQL Server Express and creates a user (user id: pwsadmin and password: pwsadmin123) as a database owner (dbo). Since Grasshopper does not support Windows authentication, this user will be used in runtime to connect to the database. From a command prompt, run the following commands:

cd <Mainsoft_install_dir>\Samples\{CS|VB}\Tomcat\PWS
sqlcmd -S .\SQLEXPRESS 
          -v PROJECTDIR="<Mainsoft_install_dir>\Samples\{CS|VB}\Tomcat\PWS" 
          -i .\personal.sql

Note: You can safely ignore the following warning:

File activation failure. The physical file name "<Path>\Personal_log.LDF" may be incorrect.

Last, set the connection string of the new out-of-process database that you just created. To do this, open the web.config file in your Visual Studio editor, and replace the Personal connection string:

<add name="Personal" 
            connectionString="Data Source=.\SQLExpress;
                            Integrated Security=True;
                            AttachDBFilename=|DataDirectory|Personal.mdf"
            providerName="System.Data.SqlClient"/>

with the following:

<add name="Personal" 
            connectionString="Data Source=.\SQLExpress;
                            Initial Catalog=personal;
                            Integrated Security=false;
                            user id=pwsadmin;
                            password=pwsadmin123" 
            providerName="System.Data.SqlClient"/>

Step 4: Configure the ASP.NET services database

ASP.NET 2.0 default membership and role providers use an embedded in-process instance of SQL Server 2005 Express to provide a persistent store for application data such as membership and roles. Grasshopper 2.0 default providers are based on Apache Derby^™, which is a pure Java embedded database.

Grasshopper implemented new providers for working with the default Derby database. The Derby providers and the connection string for working with the Derby database are defined in the machine.config file, located inside Grasshopper System.jar file (in <mainsoft_install_dir>\java_refs\framework\System.jar).

Grasshopper runtime will read the connection string for the application data database from the machine.config file. You may delete the LocalSqlServer connection string lines from the Web.Config file:

<remove name="LocalSqlServer"/>
<add name="LocalSqlServer" 
        connectionString="Data Source=.\SQLExpress;
                        Integrated Security=True;
                        User Instance=True;
                        AttachDBFilename=|DataDirectory|aspnetdb.mdf" />

Step 5: Build, run and debug the ported Personal Web Site

	Figure 10. Debugging the PWS sample

There is nothing special about building the Java EE project using Grasshopper, and that's what makes Grasshopper so appealing -- if you know how to build a C# project in the Visual Studio development environment, then you know how to build the Java version of it. All you have to do is change the configuration to Debug_Java, and launch the Tomcat application server.

You can press F5 to compile the application into MSIL, cross-compile this MSIL into Java bytecode, deploy the bytecode to Tomcat, and launch it with the Grasshopper debugger:

Your Java EE version of the PWS application looks exactly the same as in .NET, and may be used in the same manner as in .NET. To learn how to use the Personal Web Site you have just ported, read the instructions in the sample's Welcome.html page.

You may test the Grasshopper debugger now (see the debugger in action in Figure 10). Set some breakpoints and see how it works. Debugging with Grasshopper is no different than what you are used to with Visual Studio. You debug your Grasshopper projects at the source level, and may use the debugger's various windows to inspect and troubleshoot your application. Step through the application, examine the Grasshopper stack trace, and expand some objects in the Autos window.

	Figure 11. Mainsoft Web Site Administration Tool
	Figure 12. Personal Web site running on Tomcat

Welcome to Java, .NET 2.0 developers!!

Step 6: Configure users, roles, and membership

As with the .NET version of the PWS application, you can also configure users, roles, and membership for the Java EE version of the PWS sample. Open the Mainsoft Web Site Administration Tool from the ASP.NET Configuration Project menu of Visual Studio. Look at the address bar and notice that the tool is running on the Tomcat application server, under http://localhost:8080/MyWebsiteProject/aspnetconfig/Default.aspx (Figure 11).

Use the Web Site Administration Tool to create and manage users and roles for your Personal Web Site sample.

Conclusion

In this article you found how Grasshopper can be used to migrate a pretty complex Web application from C# on the Microsoft runtime, to C# on a Java EE runtime, with minimal recoding. In a similar manner, you can rehost .NET 2.0 applications to run on Linux. That’s the power of Grasshopper, and that’s just for starters.

So what do you think?