Using IP*Works! in a Google App Engine Web Application

HTTP-Based Component of a Java Edition Toolkit
  • Eclipse IDE
  • Chapter Listing

    1. Introduction
    2. Setting up Eclipse
    3. Creating a Web Application Project
    4. Adding the IP*Works! Library
    5. Using an IP*Works! Component within a Servlet
    6. Using an IP*Works! Component within a JSP Page
    7. Licensing
    8. Deploying Your Web Application
    9. Tips and Troubleshooting

    Introduction

    Support for Google App Engine was added to the HTTP-based components contained within the Java Edition of the toolkits in the Q4 2009 Subscription update on October 16, 2009.

    This tutorial will cover setting up Eclipse with the Google App Engine plugin, creating a web application using the HTTP component of the IP*Works! toolkit, and deploying the application. The setup for other toolkits will work in a similar fashion as the IP*Works! toolkit described in this tutorial.

    Setting up Eclipse

    The first step is to install the Eclipse IDE. If you do not have it installed, the setup can be found here: Eclipse IDE. As of Eclipse 3.5 (Galileo), the setup will be downloaded as a zip file. The contents of this file can be extracted and placed in the desired location.

    Once the IDE is downloaded and extracted, the next step is to install the Google App Engine plugin for Eclipse.
    Instructions for installing this plugin can be found at Google Code:

    Creating a Web Application Project

    Once the Google App Plugin is installed and the Eclipse IDE has been restarted, you can then create an application. To do this, go to: File > New > Web Application Project or you can click the "New Web Application Project" button in the toolbar. A "Project name" and "Package" can then be given to the project. Next uncheck "Use Google Web Toolkit" and ensure that "Use Google App Engine" is checked. The "Finish" button can then be clicked to create your application. Additional instructions for creating a new Web Application can be found at Google Code: Creating a Project.

    Create a new Web Application Project

    Adding the IP*Works! Library

    Once your application is created and the directory structure is set up, the next step is to add the IP*Works! JAR file to your project. Navigate to the location of the ipworks.jar file. The default location for this file is: C:\Program Files\nsoftware\IPWorks V8 Java Edition\lib. This file must be added to the "lib" directory of your project, which is located under the war and WEB-INF directories (war\WEB-INF\lib). You can drag and drop the JAR file into the "lib" folder within the Eclipse IDE, which will copy the file to that directory. The JAR file can also be copied and pasted into the actual "lib" folder itself, which is located within the workspace specified when creating the application. When doing this you may have to refresh Eclipse's Project Explorer, to view the JAR file, by right-clicking within the Project Explorer and selecting "Refresh".

    Once the JAR file is added to the "lib" folder, the next step is to add the library to the Java Build Path. You will first have to access the project properties by either right-clicking the project and selecting "Properties" or by going to the Project menu and selecting "Properties". Once the properties dialog box is displayed, select the "Java Build Path" option on the left menu, and then select the "Libraries" tab. You can then click the "Add JARs..." button and select the ipworks.jar file within the "lib" directory. Once "OK" is clicked to close out of the properties dialog, the ipworks.jar file should be displayed within the Project Explorer.

    Adding a library

    Using an IP*Works! Component within a Servlet

    The first step in creating a Servlet that contains an IP*Works! component, you must first add the import to the JAR file: import ipworks.*. You can then create an instance of the component you wish to use.

    When using a component with Google App Engine, the UsePlatformHTTPClient configuration setting must be set to true: component.config("UsePlatformHTTPClient=true");.
    If this configuration setting is not set, then an HTTP 500 error will be received similar to the following: access denied (java.lang.RuntimePermission modifyThreadGroup).

    When using the full version of the toolkit, the RuntimeLicense property must be set. If using the trial version of the toolkit, be sure that the .lic file is added to the project. More information about obtaining the RuntimeLicense and adding the .lic file to your project can be found in the Licensing section of this tutorial. The component can then be coded and used accordingly.

    Below is an example using the HTTP component within a Servlet.

    import java.io.IOException;
    import javax.servlet.http.*;
    import ipworks.*;
    	  
    @SuppressWarnings("serial")
    public class HttpurlServlet extends HttpServlet {
       public void doGet(HttpServletRequest req, HttpServletResponse resp) 
      throws IOException {
        Http http1 = new Http();
        try
        {
          http1.setRuntimeLicense("ENTER_LICENSE_STRING_HERE");
          http1.config("UsePlatformHTTPClient=true");
          http1.get("http://www.nsoftware.com");
          resp.getWriter().println(new String(http1.getTransferredData()));
        } catch (IPWorksException ex) {
          resp.getWriter().println("Exception: " + ex.getMessage());
        }
      }
    }
    	

    Using an IP*Works! Component within a JSP Page

    First create a JSP page and ensure that it is contained within the war directory of your project. Once the page is created, you must then add the import to the JAR file: <%@ page import="ipworks.*"%>. You can then create an instance of the component you wish to use.

    When using a component with Google App Engine, the UsePlatformHTTPClient configuration setting must be set to true: component.config("UsePlatformHTTPClient=true");.
    If this configuration setting is not set, then an HTTP 500 error will be received similar to the following: access denied (java.lang.RuntimePermission modifyThreadGroup).

    When using the full version of the toolkit, the RuntimeLicense property must be set. If using the trial version of the toolkit, be sure that the .lic file is added to the project. More information about obtaining the RuntimeLicense and adding the .lic file to your project can be found in the Licensing section of this tutorial. The component can then be coded and used accordingly.

    When creating a JSP page, you may encounter the following error: Your Web Application Project must be configured to use a JDK in order to use JSPs. This is most likely caused by Eclipse set to use the JRE instead of the JDK. To fix this, first open the preferences dialog by going to "Window > Preferences". Then expand "Java" and select the "Installed JREs" option. You can then click the "Add..." button, select "Standard VM", and click "Next >". You can then click the "Directory" button, navigate to the JDK directory, select it, and click finish. Next ensure that the JDK is checked and click OK.

    Adding a library

    Below is an example using the HTTP component within a JSP page.

    <%@ page import="ipworks.*"%>
    
    <%
    String url = request.getParameter("url") != null ?
      request.getParameter("url") : "http://www.nsoftware.com/";
    %>
    
    <p><i>Displays the HTML of the web page you specify:</i></p>
    <form method="post">
      <br>Web Page:
      <input type="text" name="url" value="<%= url %>" size="35">
      <input type="submit" value="  Get HTML   ">
    </form>
    
    <%
    
    if (request.getMethod().equalsIgnoreCase("POST")) {
      Http http = new Http(); 
      http.setRuntimeLicense("ENTER_LICENSE_STRING_HERE");
      http.setTransferredDataLimit(0);
      http.get(url);
    
      out.write("<hr> <h1> Contents of " + url + ":</h1>");
      String urlData = new String(http.getTransferredData());
      out.write("<pre>" + urlData + "</pre>");
    }
    
    %>
    	

    Licensing

    Full Version

    When using the full version of the toolkit, the RuntimeLicense property must be used.

    To obtain your RuntimeLicense, on the properly licensed development machine, you can create a dummy project and add an IP*Works! component to the project. You can then output the RuntimeLicense property to obtain the license string: System.out.println(component.getRuntimeLicense());. This will output a long string which can be copied and used to set the RuntimeLicense property of each component used in your Web Application project. Note that this same value works for all components included within the edition of the toolkit you are using.


    Trial Version

    When using the trial version of the toolkit, a .lic file must be used instead of the RuntimeLicense property.

    To create a .lic file, first navigate to the ipworks.jar file that was installed with the toolkit (C:\Program Files\nsoftware\IPWorks V8 Java Edition\lib). You can then either double-click the ipworks.jar file or execute the following command: java -jar ipworks.jar to create the .lic file. This file can then be added to the "lib" directory of your project (war\WEB-INF\lib), just like the ipworks.jar file was added to the project. The .lic file should reside next to the JAR file. Once the .lic file is added to the project, the application will be properly licensed.

    Deploying Your Web Application

    Applications can be deployed to App Engine by using the Google App plugin for Eclipse. The first step in deploying your application is to sign in to App Engine using your Google account. You can then create a new application by clicking the "Create an Application" button. This will then allow you to register an application ID. This ID must then be used to set the <application> element in the appengine-web.xml file, which is located in the WEB-INF directory in your project. You can then click the "Deploy App Engine Project" button on the toolbar. Your Google account information can then be entered in the dialog box. Clicking the "Upload" button will then deploy your application. Once uploaded, your application can be visited by going to the following link: http://application-id.appspot.com/.
    More information about deploying your application can be found at Google Code: Deploying Your Application

    Tips and Troubleshooting


    java.lang.NoClassDefFoundError

    This error is caused by a copy of the JAR file not being in the "lib" folder of the project. To resolve this error, add a copy of the ipworks.jar file to "lib" directory (war\WEB-INF\lib) of the project.


    java.security.AccessControlException: access denied (java.lang.RuntimePermission modifyThreadGroup)

    This error is caused by the UsePlatformHTTPClient configuration setting not being set. To resolve this error, set this configuration setting to true: [component_name].Config("UsePlatformHTTPClient=true");.


    access denied (java.io.FilePermission [directory]\ipworks.lic read)

    This error is caused by the component not being properly licensed. To resolve this error, please visit the Licensing section of this tutorial.


    Your Web Application Project must be configured to use a JDK in order to use JSPs.

    This error is caused by Eclipse being set to use the JRE instead of the JDK. Instructions on how to resolve this can be found in the second paragraph of the Using an IP*Works! Component within a JSP Page section of this tutorial.


    We appreciate your feedback.  If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.