Virtual Machinery logo BTree Session Bean Demo
Home Download code Deployment Guide Using a different BTree Redeploy after changes Security
Deployment on Sun J2EE Reference platform

The preceding sections describe how to use a BTree in a J2EE environment, the code that you can download here will allow you to demonstrate this practically. The code and the subsequent instructions have been designed for use with Suns reference J2EE environment (specifically that associated with the current version 1.4 of the J2EE tutorial – you can download the entire environment here). Provided you have a good understanding of the deployment of J2EE applications and their associated Web Clients the code should be generic enough to use in any J2EE-conformant environment.

The layout of the demo code when you run the self-extracting file should be as follows –

<INSTALL_DIRECTORY>
	\docs
		BTreeEJB.html 	//This document
		VMPhoneTest.dat	// Test BTree - data file
		VMPhoneTest.ind	// Test BTree - index file
		\images 		//Images associated with this document
	\btreedemo
		\build                 
		\src
			Accounts.java
			BTreeDemo.java
			BTreeDemoBean.java
			BTreeDemoHome.java
			BtreeRO.jar
		\web
			index.jsp
		build.xml		//build file for Sun J2EE Tutorial environment

These are all the files that you need to create and run a sample EJB with web client which shows the use of Btrees for data storage in Stateless Session Beans.

After you have extracted the files from the distribution copy the btreedemo directory in its entirety to the <INSTALL>/j2eetutorial14/examples/ejb directory. This will allow you to take advantage of the build/deploy environment provided by Sun. In essence the instructions below follow the ‘Getting started with Enterprise Beans’ chapter in the J2EE 1.4 tutorial. There are a number of different versions of Sun's deploytool but they all follow the same principles and you may have to click on the 'Sun-specific Settings' button on a panel to get to some of the functionality mentioned here.

  • Set up the CLASSPATH and PATH variables – be sure to include the BTreeRO.jar file from <INSTALL>/j2eetutorial14/examples/ejb/btreedemo/src in your CLASSPATH
  • Copy the VMPhoneTest.dat and VMPhonetest.ind to the root directory of your C drive. If you want to locate them elsewhere see the section ‘Changing the BTree used by the sample application’ below.
  • Start the server by running j2ee –verbose
  • Start deploytool by running ‘deploytool’
  • When the deploy tool starts we can create the application by doing the following –
    1. In deploytool, select File->New->Application EAR.
    2. Click Browse.
    3. In the file chooser, navigate to this directory: /j2eetutorial14/examples/ejb/btreedemo/
    4. In the File Name field, enter BTreeDemo.ear.
    5. Click New Application.
    6. Click OK.
    7. Verify that the BTreeDemo.ear file resides in the directory specified in step 3.
    8. Select the BTreeDemo entry in the tree
    9. Select the ‘General’ tab
    10. Press the ‘Add Library’ button and add the file BTreeRO.jar from the /j2eetutorial14/examples/ejb/btreedemo/src directory
  • We now compile and package the Enterprise Bean –
    1. In a terminal window navigate to /j2eetutorial14/examples/ejb/btreedemo
    2. If you haven’t included BtreeRO.jar in your CLASSPATH (As described above) do so now
    3. Run ‘asant build’. If you get problems here it is more than likely related to the setup of your PATH and CLASSPATH variables and you should check the J2EE Tutorial setup for details.
    4. In deploytool, select File->New->EnterpriseBean.
    5. Click Create New JAR.
    6. Select BtreeDemo as the App name
    7. In the JAR Display Name field, enter BTreeDemoJAR.
    8. Click Edit. And in the tree under Available Files, locate the btreedemo/build subdirectory.
    9. In the Available Files tree select these classes: Accounts.class, BTreeDemo.class, BTreeDemoBean. class, and BTreeDemoHome.class and Click ‘Add’ then Click ‘OK’ then Click ‘Next’.
    10. Open the ‘General’ dialog box
    11. Under Bean Type, select the Session button.
    12. elect the Stateless button.
    13. In the Enterprise Bean Class combo box, select btreedemo.BTreeDemoBean.
    14. In the Enterprise Bean Name field, enter BTreeDemo.
    15. In the Remote Home Interface combo box, select btreedemo.BTreeDemoHome.
    16. In the Remote Interface combo box, select btreedemo.BTreeDemo.
    17. Click Next until you get to the last tab then click Finish.
  • Next we package the Web Client
    1. Select File->New->Web Component.
    2. Select the button labelled Create New WAR Module in Application.
    3. In the combo box below this button, select BTreeDemo.
    4. In the WAR Display Name field, enter BTreeDemoWAR.
    5. Click Edit and in the tree under Available Files, locate this directory:
    6. <INSTALL>/j2eetutorial14/examples/ejb/btreedemo/web/
    7. Select index.jsp.
    8. Click Add then click OK then click Next.
    9. In the Choose Component Type dialog box select the JSP button and click Next.
    10. In the Component General Properties dialog box in the JSP Filename combo box, select index.jsp.
    11. Click Finish.
  • Then we map the WEB clients EJB References –
    1. In the tree, select BTreeDemo WAR.
    2. Select the EJB Ref’s tab.
    3. Click Add.
    4. In the Coded Name field, enter ejb/BTreeDemo
    5. In the EJB Type field, select Session.
    6. In the Interfaces field, select Remote.
    7. In the Home Interface field, enter btreedemo.BTreeDemo Home.
    8. In the Local/Remote Interface field, enter btreedemo.BTreeDemo.
    9. In the JNDI Name field, select or enter BTreeDemoBean.
    10. Click OK.
  • Then we need to map the EJB references –
    1. In the tree, select BTreeDEmo.
    2. Select the JNDI Names tab.
    3. In the Application table the Component type should be EJB, the Component BtreeDemo and the JNDI name for the enterprise bean should be BTreeDemoBean.
    4. In the References table the Ref. Type should be EJB Ref, Referenced by BTreeDemoWAR, reference name ejb/BtreeDemo and JNDI Name BTreeDemoBean
  • Then we need to specify the Web Context –
    1. In the tree, select BTreeDemo.
    2. Select the Web Context tab.
    3. In the Context Root field, enter /btreedemo.
  • Now we select Tools -> Deploy to deploy the application.
  • Finally we connect to the application by opening the following URL –
    http://localhost:8000/btreedemo
  • You should now be able to enter an account number using the Browser. Pressing ‘Get Details’ will return the details of that account. The sample BTree included in the distribution holds 10000 records (i.e. account numbers from 1111111 to 1121110).
Changing the BTree used by the sample application

The sample application can use any BTree generated by Virtual Machinery’s BTree implementation – this includes those generated by the Java and Smalltalk versions of the code and those generated by the demo application which is downloadable from the Virtual Machinery website.

If you wish to change the details of the BTree accessed by the sample application you will need to change the Accounts.java file and rebuild and re-deploy the application (see section below).

You only need to change 1 line in the Accounts.java file –

accountsInstance = new Accounts(new com.virtualmachinery.btreero.btree.BTreeRO( "C:\\VMPHONETEST.DAT","C:\\VMPHONETEST.IND",3,132));

If you change the locations, and/or names, of the BTree then you should change the first two parameters. The second two parameters refer to the number of index and data pages, respectively, that will be cached by the BTree. In the sample application as delivered we cache the entire BTree – i.e. 3 index pages and 132 data pages. You can try altering these to see how performance is affected. If you use a different BTree you may want to change these parameters to reflect the size of your new datasets and to experiment with the performance of the BTree. Remember that your cache is using VM memory so a very big cache may start to generate OutOfMemory exceptions and you may have to increase the amount of memory available to your VM. As the cache is primed on the initialization of the single instance (using the loadmem() method) a very large cache may slow this initialization. You can comment out the call to loadmem if you wish and each page will then be cached as it is used.

Obviously if this is a BTree that you have created yourself using the Virtual Machinery implementation you will know the numbers of index and data pages in the BTree. If you used the downloadable demo to create the BTree you can calculate the numbers of index and data pages using the following –

Index Pages = ((Size of VMPhoneTest.ind file in bytes) – 512) divided by 512

Data Pages (tree contains less than 4500000 (4.5 million) records) = ((Size of VMPhoneTest.dat file in bytes) – 4096) divided by 4096

Data Pages (tree contains more than 4500000 (4.5 million) records) = ((Size of VMPhoneTest.dat file in bytes) – 8192) divided by 8192

Don’t worry about being exact with the cache size the code won’t throw an exception if a cache is bigger than the number of pages available.

Rebuilding and re-deploying the sample application

If you change any of the java files you will have to recompile the code and rebuild using the -

asant build

command outlined above.

You should then use the ‘Update files’ and ‘Deploy’ options to re-deploy the application on the server.

If you have changed the .jsp page you will probably have to hit the ‘refresh’ button on your browser.

Security Issues

The Java platform’s security environment may prevent your application from accessing files in certain situations unless you have adequate permissions. These permissions are generally held in a .policy file. If you are working in a development environment you can easily add permission to access the BTree files by adding the following grant to the policy file –
grant {
    permission java.io.FilePermission "<>", "read,write";
};

A Quick guide to BTrees gives an overview of the underlying principles of BTrees. You can also find details about Virtual Machinery's BTree implementation here. You can buy Virtual Machinerys BTree implementation online - just click on the button to the right.

These classes are Copyright Virtual Machinery 1990,2004 - All Rights Reserved and are provided acording to the terms of the license.