Installation Guide for the Plumtree Enterprise Development Kit (EDK) 5.3 Java

This page provides information on EDK installation and deployment. For additional documentation and related resources, see the index.

EDK Installation

Before installing the EDK, confirm that your system meets the requirements listed in the Release Notes. Extra steps are required to support the Logging API, explained below.

Unzip the edk_java.zip or edk_java.tar.gz file into the root Plumtree folder, typically C:\Program Files\plumtree. The following subfolders will be created in the \ptedk folder:

- \devkit contains the WEB-INF folder used to build Web Applications. Make sure all of the Jar files are in your application's class path or Web Application's War file. See Deployment below for more details on creating services.
- \documentation includes the API documentation (javadocs). For the latest EDK API documentation, see the Plumtree Developer Center.

Note: servlet.jar 2.2 or 2.3 must be in the CLASSPATH.

EDK Upgrade

Upgrading your EDK version allows your application to take advantage of new APIs. See the Logging API section to learn about upgrading your existing EDK-based applications to take advantage of Plumtree's logging framework.

EDK 5.2 and above includes different dependencies than previous releases. Copying the new edk.dll will not result in a full installation. Make sure to copy the files located in the /bin folder and overwrite your existing EDK assemblies to add new dependencies and updated versions of old dependencies.

Logging API (Plumtree Logging Toolkit)

EDK 5.2 and above provides a remote logging API for use with Plumtree Logging Utilities. To support this feature, you must download and install the Plumtree Logging Utilities package from the Plumtree Developer Center.

To enable logging in the EDK when run as a Web application, edit the web.xml file provided with the Java EDK distribution. (See the note below about the new web.xml.) Look for the following settings after the end of the servlet mappings, and before a group of similar settings defining the service implementations.

> <env-entry>
> <env-entry-name>ptedk.LoggingApplicationName</env-entry-name>
> <env-entry-value></env-entry-value> <!-- if empty will not log -->
> <env-entry-type>java.lang.String</env-entry-type>
> </env-entry>

> <env-entry>
> <env-entry-name>ptedk.LogToNetwork</env-entry-name>
> <!-- value=false : log only to local machine if logging enabled (default) -->
> <!-- value=true : log to network via IP multicast if logging enabled -->
> <env-entry-value>false</env-entry-value>
> <env-entry-type>java.lang.Boolean</env-entry-type>
> </env-entry>

> <env-entry>
> <env-entry-name>ptedk.VerboseLogging</env-entry-name>
> <!-- value=false : do not log parameters and return values (default) -->
> <!-- value=true : log potentially sensitive parameters and return values -->
> <env-entry-value>false</env-entry-value>
> <env-entry-type>java.lang.Boolean</env-entry-type>
> </env-entry>

- EDK logging is disabled if the value of ptedk.LoggingApplicationName is empty or the entry is absent. To enable sending log messages, set its value to a string of 1-32 characters (ASCII letters and numbers plus space, hyphen, underscore, and period). To receive log messages, use this same value to configure Plumtree Logger or Plumtree Debugging Spy from the Plumtree Logging Toolkit. (For details, see Configuring Logging Receivers on the Developer Center.)
- If ptedk.LogToNetwork is left at its default "false" value, only log receivers running on the same machine as the EDK will be able to receive log messages. Set this to "true" to be able to pick up logs on the local network.
- If ptedk.VerboseLogging is left at its default "false" value, the Portlet API and Integration Web Services (Auth, Crawler, Profile, and Search) will provide tracing of remote method calls and exceptions but will not log parameters and return values. Set it to "true" to log parameters and return values of remote method calls.

If you are upgrading and wish to use your existing web.xml file, insert the above configuration block into the file immediately before the closing </web-app> tag and set the values as appropriate.

To activate logging outside a Web application context, refer to the API documentation for the com.plumtree.remote.logging package.

Deployment

Follow the steps below to deploy the Java version of the EDK.

Note: These deployment steps are for EDK version 5.2 and above. Previous versions for the EDK used the Deploy Servlet to generate a server-config.wsdd file; it has been removed and is no longer supported. In EDK 5.2 and above, the implementation classes can be specified in ptedk\<version>\devkit\java\WEB-INF\web.xml without modifying server-config.wsdd. The new web.xml must be used in conjunction with the new server-config.wsdd. Using the new web.xml with an old server-config.wsdd is not supported. However, use of the new web.xml/server-config.wsdd files is not required and older versions of web.xml/server-config.wsdd can still be used with the new EDK.

1. Deploy the EDK in your application server. For BEA WebLogic or Apache Tomcat, follow the instructions below. (For IBM WebSphere, you must create a .war or .ear file that is compatible with WebSphere. See the WebSphere documentation for detailed instructions. )
   1. Create a folder called \edk in the application server's \webapps directory. (For example, if Tomcat is installed in C:\tomcat, the path might be C:\tomcat\webapps\edk.)
   2. Navigate to the EDK installation directory and copy the \WEB-INF and its \lib subfolder from <installdir>\ptedk\<version#>\devkit\WEB-INF folder to the new \webapps\edk directory in the application server. This loads Apache AXIS into the application server.
   3. Confirm that Apache AXIS is available by opening the following page in a Web browser: http://<hostname:port>/edk/servlet/AxisServlet (change hostname:port to fit your application server, for example, localhost:7001 for BEA Weblogic). The browser should display the message "And now... Some Services" and a list of installed services.
2. Compile the class that implements the EDK interface and copy the entire package structure to the appropriate location in your Web application (usually the \WEB-INF\classes directory).

After you have completed the steps above, your system is set up for development against the Java EDK. For details on deploying services, see Deploying EDK Services on the Developer Center. For links to additional documentation and related resources, see the index.