Programmer's Guide Introduction

General Information.
The Role of your Application.

FPCS and FPVB Interface Examples

Setting up C# and Visual Basic .NET Projects.
Application Structure.
Testing the Examples.

FPServer Interface Examples

Introduction.
The FPTest Example Document.
The VBScript and JScript ASP Examples.
Testing the Example.

Java Native Interface Example

Introduction.
The FPJNI Bridge.
The FPTest Example Document.
The FPTest.java classes.
Testing the Example.

ASP, ASPX, JSP, and FPWeb Setup

Common Setup Instructions
Active Server Pages General Setup
Active Server Pages FPWeb Setup
Java Server Pages General Setup
Java Server Pages FPWeb Setup



General Information

Note: All FinerEdge Publisher components (in particular the main FPEngine dynamic link library) and interfaces are multi-threaded capable (i.e., thread-safe).

FinerEdge Publisher documents are XML-based entities that reside externally from the applications that use them. As such, FinerEdge Publisher documents can be created and updated independently of an organization's applications. Also, FinerEdge Publisher documents can be created and maintained by a wider range of individuals than can documents that are generated directly from within application code.

The personalization of FinerEdge Publisher documents comes from within the documents themselves. Document authors can use line-of-business data in concert with conditional processing tags and conditional formatting styles. As such, line-of-business data can be easily merged into documents in a number of ways to create custom looking paragraphs, fields, tables, etc.

This document presents a number of FinerEdge Publisher interface examples. In addition, the following table assists in determining which type of interface will best meet your needs relative to the programming environment being used:

C#	FPWriterNET, FPFormNET (Windows .NET Form Controls). (Both of these controls are contained within FPNET.dll)
Visual Basic .NET	FPWriterNET, FPFormNET (Windows .NET Form Controls). (Both of these controls are contained within FPNET.dll)
Visual Basic (and languages supporting ActiveX controls)	FPWriter, FPForm (ActiveX Controls).
C++ (All)	FPWriter, FPForm (ActiveX Controls), or FPEngine.dll (FPEngine.h).
Java, JSP	FPJNI (Java Native Interface).
ASP, ASP.NET	FPServer (Dual Interface Automation Server)

» Back to the Table of Contents. «

The Role of your Application

The role of an application with FinerEdge Publisher is two-fold. First, the application can make use of a number of high-level properties and methods to generate entire documents in multiple different output formats.

Secondly, the application can supply either none, some, or all of the line-of-business data that will be used in the generation of documents. The line-of-business data can come from databases, XML data files, fields on a form, etc.

FinerEdge Publisher comes complete with built-in database and XML data facilities to perform most, if not all, of the data access itself. In this case, your application might elect to only supply a small amount of initial information in order to control document generation.

The common mechanism for importing external information into a document from database data sources, XML files, and applications is described in the section "Application Data Interface" within the FinerEdge Publisher Reference Manual.

» Back to the Table of Contents. «


Setting up C# and Visual Basic .NET Projects

For both the C# (FPCS) and Visual Basic .NET (FPVB) interface examples, you'll need to first update the FPNET reference. Please initiate Visual Studio 2005 (or greater release) and open the supplied projects FPCS.csproj and FPVB.vbproj located under the FPCS and FPVB installation directories, which will normally be located in the directory C:\Program Files\FinerEdge Software\FinerEdge Publisher.

For the project FPCS, locate the reference FPNET under the References folder in the solution explorer and delete the reference. Right-click on the References folder and select "Add Reference". Use the Browse tab to locate and select FPNET.dll, which will normally be in the directory C:\Program Files\FinerEdge Software\FinerEdge Publisher. Finally, please save the project.

For the project FPVB, double-click on "My Project" and select the References tab. Delete the reference "FPNET" and then press the "Add" button. Use the Browse tab to locate and select FPNET.dll, which will normally be in the directory C:\Program Files\FinerEdge Software\FinerEdge Publisher. Finally, please save the project.

» Back to the Table of Contents. «

Application Structure

The FPCS (C#) and FPVB (Visual Basic .NET) application examples demonstrate how to use the FPWriterNET and FPFormNET .NET Windows Form Controls in a very straightforward manner. In the demonstration example documents (i.e., located under the Docs installation directory), most of the external information comes from either the FPDemo example database or a supplied XML data file (generated from the FPDemo database). As you'll see, only a few items of control information, retrieved by automatically generated forms attached to the documents, are needed to customize a particular document's output. Note: It's also possible for all external information to come directly from applications without using FinerEdge Publisher's build-in database query and XML data facilities.

The FPCS and FPVB applications are C# and VB.NET (i.e., Visual Basic .NET) Visual Studio 2005 projects respectively. To work with these examples, please initiate Visual Studio 2005 (or greater release) and open the supplied projects FPCS.csproj and FPVB.vbproj located under the FPCS and FPVB installation directories, which will normally be located in the directory C:\Program Files\FinerEdge Software\FinerEdge Publisher. After opening the FPCS and FPVB projects, you will see two forms called FPWriter and FPForm. FPForm hosts the FPFormNET .NET Windows Form Control, but otherwise contains no actual code. FPFormNET is used only if a document has an attached form in order to gather certain preliminary information for the document.

The FPWriter form hosts the FPWriterNET .NET Windows Form Control, two buttons, and two corresponding labels. Please open the code view for the FPWriter form to display the controlling code. All code is contained in three methods. Two methods correspond to the two buttons previously mentioned, while the third method is a private helper function that detects and processes a form attached to a particular document (if one exists).

As you can see, the entire functioning FPCS and FPVB applications were implemented with a minimum amount of application code, but are still capable of processing all supplied demonstration examples (and most other documents as well. We recommend that you take a moment to examine the structure of the code along with the embedded comments.

» Back to the Table of Contents. «

Testing the Examples

From Visual Studio 2005 (or greater release), and with either the FPCS.csproj or FPVB.vbproj opened, please press the F5 function key on your keyboard to compile and run the FPCS or FPVB example application. After the FPWriter startup form is shown, please press the "Catalog" button. Locate and select the supplied catalog file, which will normally be in the directory C:\Documents and Settings\Your User Name\My Documents\FinerEdge Software\FinerEdge Publisher\Environ.

Next, press the "Document" button. Locate and select one of the demonstration documents supplied with your installation. The demonstration documents are normally in the C:\Documents and Settings\Your User Name\My Documents\FinerEdge Software\FinerEdge Publisher\Docs directory. If the document has a corresponding form, it will be shown prior to rendering the document. Make any selections you like on the form and close the form dialog window. In either case, the document is then processed, rendered, and shown within the FPWriter form.

While you can select additional documents with the "Document" button, you do not need to set the "Catalog" again within the current execution (unless of course you want to use a different catalog). Note: All other cross-media generation capabilities are available from either the FPWriterNET or FPWriter controls as well. However, we elected to keep the FPCS and FPVB examples as straightforward as possible for demonstration purposes.

» Back to the Table of Contents. «


Introduction

FinerEdge Publisher includes an Automation Server interface called "FPServer.dll". FPServer has a dual interface implementation which supports the IDispatch interface (i.e., late binding) for VBScript and JScript (i.e., JavaScript) compatibility.

The FPServer interface includes all FinerEdge Publisher functionality except the ability to directly view documents (from the built-in viewer) and support for events. The choice to use one interface versus another may depend upon your requirements. The following table provides some assistance with this decision:

●	If you need to access FinerEdge Publisher from server-side web page implementations (e.g., ASP) in order to generate cross-media outputs, you'll need to use the FPServer interface.
●	If you need to access FinerEdge Publisher from Java Server Pages (JSP) in order to generate cross-media outputs, you'll need to use the FPJNI interface.
●	If you need to View documents from within your application (i.e., not using, for example, an external PDF viewer), you'll need to use the FPWriter interface control.
●	If you need to communicate with FinerEdge Publisher extensively from your application, you'll need to use the FPWriter interface control. However, please keep in mind that the FPServer interface does support the ability to set initial variables (say, from a form), and access all database sources and XML Data.

The FPServer Automation Server interface was primarily designed for web-based environments or development platforms that either don't support the FPWriter control or only support the IDispatch interface for late binding such as VBScript and JScript (i.e., JavaScript).

Note: The IDE form definition view has the ability to automatically generate both ASP and JSP scripts for documents and forms. The ASP examples shown herein provide additional explanation for those individuals that want to create their own scripts.

» Back to the Table of Contents. «

The FPTest Example Document

The "FPTest.fpm" document can be found in the "Docs" folder within your FinerEdge Publisher installation directory. This document is used with "FPTestVB.asp" and "FPTestJS.asp" to provide Active Server Page examples illustrating how to call the FPServer interface from both VBScript and JScript (i.e., JavaScript).

The "FPTest.fpm" document simply displays the contents of five variables having the types Long, Double, String, Date, and Time. These variables are created and initialized from both the "FPTestVB.asp" and "FPTestJS.asp" example scripts.

» Back to the Table of Contents. «

The VBScript and JScript ASP Examples

The VBScript and JScript ASP examples, called "FPTestVB.asp" and "FPTestJS.asp" respectively, can be found in the "Demo" folder within your FinerEdge Publisher installation directory. (A production ASP script would normally be much more substantial in addition to dynamically setting the document and resulting file names, possibly obtained from a database query.)

A number of comments labeled "TODO" can be seen at the beginning of the scripts. The lines having the "TODO" text within a comment represent code that you'll need to change to your own environment during the "Testing the Examples" topic below.

Often times, in an ASP script, you'll want to let FinerEdge Publisher handle most of the database extraction and XML Data processing. FinerEdge Publisher documents can easily combine these input mechanisms in a manner that document authors can easily modify. In addition, documents can handle embedded recordsets of data where the result of one recordset drives the data extraction of an inner recordset.

However, the ASP script may want to drive the outermost recordset queries itself. Also, there might be certain situations where the ASP script may even want to perform most of the data extraction itself. The data fed into FinerEdge Publisher from an ASP script takes the form of "external variables" to the document author. External variables can even be arrays.

By convention, any FinerEdge Publisher variables created and populated by the ASP script prior to calling the "CreateDocument" method are placed within the "Global" recordset. The format for a FinerEdge Publisher external global variable is:


Where <name> can include alphanumeric characters or underscores and is case sensitive. In addition, the <name> can also be suffixed with brackets enclosing an array index (i.e., a whole number).

Five variables are created and populated from each of the ASP scripts representing different data types. These variables are displayed by the "FPTest.fpm" example document. The five variables in the VBScript example are created and populated by the following FPServer interface methods:


The five variables in the JScript (i.e., JavaScript) example are created and populated by the following FPServer interface methods:


Within the "FPTest.fpm" example document, the five external variables that are created by both the VBScript and JScript examples appear as follows:


» Back to the Table of Contents. «

Testing the Example

Since our two examples presented above use server-side scripting, you'll need to install them on your test Web Server prior to using them. You'll also need to install FinerEdge Publisher on your test Web Server at the same time. Once you've deployed FinerEdge Publisher and the two example ASP files to the Web Server, you can test the VBScript example by typing in the following URL into your Browser:


If everything is configured properly you should see a web page containing a link within your Browser. Since this example generates a PDF file, clicking on the link will initiate Acrobat Reader to display the document (provided Acrobat Reader is installed on your workstation).

Next, let's test the JScript (i.e., JavaScript) example by typing in the following URL into your Browser:


Again, clicking on the resulting link will initiate Acrobat Reader to display the newly created document.

» Back to the Table of Contents. «


Introduction

FinerEdge Publisher includes a Java Native Interface (JNI) called "FPJava.dll". This interface was primarily developed for use with server-side Java programs or Java Server Pages (JSP). The FinerEdge Publisher JNI has been tested with the Java Development Kit from Sun Microsystems, Inc.

The FPJava DLL supports all FinerEdge Publisher functionality (including events) except the ability to directly view documents (e.g., the built-in FPWriter viewer).

» Back to the Table of Contents. «

The FPJNI Bridge

The FPJava.dll and the FPJNIDefs.java files (and FPJNIEvents.java interface) are the software pieces that comprise the bridge into the FinerEdge Publisher system. The FPJava.dll provides the JNI compatible C++ side of the bridge and also directly assists in accessing FinerEdge Publisher's built-in database facility. In turn, FPJava.dll DLL links with the FPEngine DLL (i.e., FinerEdge Publisher rendering engine).

The FPJNIDefs.java and FPJNIEvents.java files provides the Java side of the JNI bridge into FinerEdge Publisher. When this class and accompanying event interface are employed, the facilities of FinerEdge Publisher are immediately available to the Java program, to include access to database queries and XML data file sources.

The FPJava.java bean class was created as a class wrapper for FPJNIDefs.java and FPJNIEvents.java. This single point of contact allows both Java programs and JSPs to easily instanciate an FPJava object and thereby gain a consistent and easy access into the FinerEdge Publisher system. In addition, the compiled classes FPJNIDefs, FPJNIEvents, and FPJava are also packaged into a JAR file, which can be found in your FinerEdge Publisher FPJNI directory.

» Back to the Table of Contents. «

The FPTest Example Document

The FPTest.fpm document can be found within the "Docs" folder of your FinerEdge Publisher installation directory. This document is used with FPTest.java to provide a JNI example illustrating how to call the FPJava DLL from Java.

The FPTest.fpm document simply displays the contents of five variables having the types Long, Double, String, Date, and Time. These variables are created and initialized to their respective test values by the supplied Java test program.

» Back to the Table of Contents. «

The FPTest.java program

There are three classes within the FPTest.java file. The public class "FPTest" contains the "main" entry point method. This method, in turn, creates an instance of the "FPTestFrame" class. The "FPTestFrame" class then creates an instance of the "FPTestPanel" class to perform the actual calls to the FPJNI facility. A number of comments labeled "TODO" can be seen at the beginning of "FPTestPanel" class. The lines showing the "TODO" text within a comment represent code that you'll need to change to your own environment.

The "FPTestPanel" class creates a PDF file from the FPTest.fpm example document (although you can easily modify it to do much more). Creating the PDF file is accomplished entirely within the "actionPerformed" method for the btnTest button with very little code. If the FPJava instance has not been created, it will be created by the following line of code:


We'll then create and initialize our external variables that are displayed by the FPTest.fpm example document. Next, we'll perform the processing and rendering of the FinerEdge Publisher document with the following JNI method calls:


If an error occurs during processing, we'll detect it and display the pertinent information within the labels of our test panel as follows:


However if no error occurs during processing, we'll generate the PDF file from the rendered document and report a successful generation within the labels of our test panel as follows:


And finally, after generating the PDF file, we'll explicitly release any memory resources that are held during document processing as follows (although, this is not strictly necessary as memory resources will be automatically released when a new document is processed or your process detaches from the FPJava DLL):


Note: If you wanted to generate a PDF file and also an XPS file from the same document, you would call the JNI methods "GeneratePDF" followed by "GenerateXPS" prior to calling the JNI method "Close".

In most instances, calling programs should let FinerEdge Publisher handle most of the database extraction and XML input data processing. FinerEdge Publisher documents combine these inputs in a manner that document authors can easily maintain themselves. In addition, documents can easily handle embedded recordsets of data where the result of one recordset drives the data extraction of an inner recordset.

However, a Java program may want to drive the outermost recordset query or supply some initialization parameters. Also, there might be certain situations where the Java program may even want to perform all of the data extraction itself.

The data fed into FinerEdge Publisher from a Java program takes the form of "external variables". External variables can also be arrays where each element may be a different data type if desired (please refer to the FinerEdge Publisher reference manual for more information on FinerEdge Publisher arrays).

By convention, any FinerEdge Publisher variables created and populated by the Java program prior to calling the "CreateDocument" method are placed within the "Global" recordset. This is in contrast to recordset variables that are created during event calls to the "InitRecord" and "GetRecord" interface methods. The format for a FinerEdge Publisher external variable that is created prior to the call to the "CreateDocument" method is:


Where <name> can include alphanumeric characters or underscores and is case sensitive. In addition, the <name> can also be suffixed with beginning and ending brackets that enclose an array index specified as a whole number.

Five variables are created and populated from the FPTestPanel class that represent different data types. These variables are displayed in the FPTest.fpm example document output. The five variables in the FPTestPanel class are created and populated by the following FPJava methods:


Within the FPTest.fpm example document, the five external variables that are created by the FPTestPanel class appears as follows:


» Back to the Table of Contents. «

Testing the Example

Prior to testing the FinerEdge Publisher JNI and working with the source code, you'll need to insure that you have a Java Virtual Machine (VM) and associated environment that supports Sun's Java Native Interface (JNI) installed on your Workstation.

After insuring that you have a compatible environment, you can compile FPTest.java and subsequently run the resulting FPTest.class. When the "JNI Tester" dialog appears, press the "Test" button to generate the PDF file from the FPTest document. The resulting PDF file can then be displayed using Adobe's Acrobat Reader.

» Back to the Table of Contents. «


Common Setup Instructions

In order to automatically generate FinerEdge Publisher ASP, ASPX, and JSP processes from the IDE's form definition view or to utilize FPWeb, some setup is required. Note: If you only wish to use FPWeb, you can proceed to the applicable "Active Server Pages General Setup" or "Java Server Pages General Setup" sections that follow.

As can be seen by the form tab within the IDE preferences or by the form properties dialog within the form definition view, five fields exist that control where the ASP, ASPX, and JSP processes are generated as well as the location where the cross-media outputs are produced by these processes. If any form properties are set, they will override any corresponding IDE form preferences that are set. Likewise if any IDE form preferences are set, they will override any corresponding environment variable settings. The five fields are as follows:

ASP url	The Active Server Page (ASP/ASPX) url that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_ASP_HTTP" is used if it has been set (otherwise, a value of "http://localhost" is used).
ASP path	The Active Server Page (ASP/ASPX) path prefix that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_ASP_HOME" is used if it has been set (otherwise, a value of "C:\Inetpub\wwwroot" is used).
JSP url	The Java Server Page (JSP) url that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_JSP_HTTP" is used if it has been set. However, if not overridden by the form properties or the environment variable "FP_JSP_HTTP", the value for the environment variable "CATALINA_HOME" is used if it has been set (otherwise, a value of "http://localhost:8080" is used).
JSP path	The Java Server Page (JSP) path prefix that is generated for the form. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_JSP_HOME" is used if it has been set (otherwise, a value of "C:\webapps\ROOT" is used).
Temp dir	The temporary path that is used to store all cross-media output files generated while running the process. If not overridden by the form properties, the value for the corresponding IDE form preferences is used if it has been set. If the corresponding value of the IDE form preferences has not been set, the value for the environment variable "FP_TEMP_DIR" is used if it has been set (otherwise, the value of the temporary path name known by the system is used). Note: The FPServer is usually run by either IIS or a JSP container under the anonymous user, which defaults to the system level temporary folder name. If either ASP, ASPX, or JSP scripts were generated by the IDE while running under a user with a profile-level temporary folder, this field (or the environment variable "FP_TEMP_DIR") may need to be set to the system level temporary folder name for proper script generation to occur.

Please take a moment to consider the above information and decide if the default values are acceptable or if you should set any of the IDE form preferences or the "FP_..." environment variables described above. Environment variables are set by selecting the "System" icon in the Control Panel. Then, select the "Advanced" tab and press the "Environment Variables" button. You will normally want to set the above environment variables as "System variables".

» Back to the Table of Contents. «

Active Server Pages General Setup

An Active Server Pages (ASP/ASPX) container is required for the FinerEdge Publisher ASP/ASPX processes to execute. The Microsoft Internet Information Services (IIS) web server is normally utilized as the ASP/ASPX container. For example on professional editions of Windows XP, IIS can be setup by invoking the "Add or Remove Programs" function in the Control Panel. Click on the Add/Remove Windows Components, select Internet Information Services, and follow the installation instructions.

On Vista, IIS7 can be setup by invoking the "Programs and Features" icon in the Classic View of the Control Panel. Click on the "Turn Windows Features On or Off" and select the "Internet Information Services" -> "World Wide Web Services" -> "Application Development Features". Insure that ASP and ASP.NET are checked and follow the installation instructions. Lastly, please insure that IIS is started on your machine.

Important: The folder name set by the "Temp dir" field or the FP_TEMP_DIR environment variable must correspond to a virtual directory that points to the system's temporary folder (e.g., "C:\Windows\Temp"). In addition, the "Temp dir" virtual directory must be set with read and write access for the anonymous web user, but should *not* have any other privileges set (especially script and execute privileges).

From the Internet Information Services management console, select the Default Web Site (or the intended web site) and press the right mouse button. Choose the menu option "New" followed by "Virtual Directory". Set the "Alias" to the value of the "Temp dir" field (e.g., "Temp") and the "Directory" to the location of the system's temporary folder (e.g., "C:\Windows\Temp"). If the virtual directory for "Temp dir" has not been defined properly or does not correspond to the system's temporary folder, the process will fail to locate the generated output files.

On Vista x86 and x64, IIS7 uses Application Pools to manage how applications are executed in IIS and their respective privileges. The IIS Application Pool where the FPServer executes will need privileges for reading and writing files (especially to the Temp directory). The Identity property of the Application Pool is one way to affect application privileges and supplies an easy way to test an initial installation. However, restricting application privileges by only allowing files to be read/written to specific directories is generally a better solution.

On Vista x64 and II7, and when running the 32-bit version of FinerEdge Publisher, an Application Pool will need to be created that has the property "Enable 32-Bit Applications" set to True. That is, 32-bit components can only be run from an Application Pool that has the "Enable 32-Bit Applications" property set.

» Back to the Table of Contents. «

Active Server Pages FPWeb Setup

Note: Prior to performing the setup instructions in this section, the instructions in the prior section "Active Server Pages General Setup" need to be performed.

Now that the prior section has setup the Temp alias for generated documents, the FPWeb user directory needs to be created with the proper privileges so that a particular user's query definitions can be stored and subsequently used to generate documents. There are many different ways to structure your user directories, including automatically inheriting privileges into sub-directories. However, we'll just setup the single user directory "FPUser" for the purpose of demonstration.

Note: In order to set the necessary privileges for the default "FPUser" directory, the "Security" tab on the directory properties dialog must be enabled if it's not already visible. To enable the "Security" tab, navigate to your control panel and select "Folder Options". Next, select the "View" tab and scroll to the bottom of the list. Click off (disable) the option "Use simple file sharing" and close the "Folder Options" dialog and the control panel.

From the Windows Explorer, locate the directory "C:\Inetpub\wwwroot" and create a new subdirectory called "FPUser". Right-click on the new FPUser directory and select "Properties". Click on the "Security" tab and select the group "Everyone". (If "Everyone" does not already exist, click the "Add" button to insert the "Everyone" group).

Click on the "Advanced" tab, subsequently select the "Everyone" group from advanced dialog, and press the "Edit" button. Select "Apply to this folder and files, and click on the options "List folder/read data", "Read attributes", "Read extended attributes", "Create files/write data", "Create folders/append data", "Write attributes", "Write extended attributes", "Delete", and "Read permissions". (All other options should be clicked off/disabled.) Finally, close all directory properties dialog boxes. (Note: If the "Delete" option is not enabled, a user will not be able to delete their own query definitions.)

As an option, the supplied FPSample.fpm template uses an image in its header. However to allow this image to show, please create a directory called "Images" under the newly created "FPUser" directory. Then, copy the "FinerEdge.jpg" image from the adjoining directory "FPWebASP\Images" to "FPUser\Images". (In general, you may want to consider having an "Images" directory under each user directory to allow your users to upload images they may want to see in their generated report headers.) You can also optionally customize the look and feel of FPWeb by updating the FPHeader.htm and FPFooter.htm files.

Important: Copy the entire supplied folder FPWebASP (in the FinerEdge Publisher installation directory) under the directory "C:\Inetpub\wwwroot" (i.e., at the same level as the newly created FPUser directory). Locate and open (in NotePad or another editor) the file "FPConfig.asp" within the newly copied FPWebASP directory. Modify any needed settings to reflect your system's configuration and save the file. (At minimum, you'll need to change "My User" in the variables "strCatalogFile" and "strTemplatePath" to reflect the user name of the system profile where FinerEdge Publisher was installed.)

Note: In a production environment, each user would signon with their own usercode instead of using the default "FPUser". A front-end web page would therefore need to set the session variable "UserName" to the applicable usercode prior to redirecting the user to "FPWeb.asp". In addition, the sub-directory corresponding to the UserName would need the same folder permissions as were previously outlined for FPUser.

» Back to the Table of Contents. «

Java Server Pages General Setup

A Java Server Pages (JSP) container is required for the FinerEdge Publisher JSP processes to execute. A free JSP container called "Tomcat" is available from the Apache Group (Apache Jakarta Project) at "http://jakarta.apache.org". Tomcat can be setup by downloading the Windows install version from the Internet and following the installation instructions. After a successful installation, please insure that the JSP container is started on your machine.

Next, please copy the FPJava.jar file, supplied with the FinerEdge Publisher installation into the appropriate directory for Java ARchive (JAR) files within your JSP container (e.g., "webapps/ROOT/WEB_INF/lib"). (If the "lib" directory does not exist under the path "webapps/ROOT/WEB_INF", you'll need to create it first.) The FPJava.jar file contains the FPJava Bean that the Java Server Pages (JSP) call in order to generate documents. In turn, the FPJava Bean communicates with the FPJNI.dll (i.e., Java Native Interface), which acts as a bridge into the FPEngine.dll. (The path to the FinerEdge Publisher components, including FPJNI.dll and FPEngine.dll, was appended to your system path environment variable during installation. In certain cases, you may need to reboot your machine in order for the modified environment variable to take effect.)

Important: The folder name set by the "Temp dir" field or the FP_TEMP_DIR environment variable must correspond to a server context that points to the system's temporary folder (e.g., "C:\Windows\Temp"). In addition, the "Temp dir" server context must be set with read and write access for the anonymous web user, but should *not* have any other privileges set.

FinerEdge Publisher has been successfully tested with all recent Tomcat versions. However starting with version 5.5, the admin tool is no longer is bundled along with the Tomcat core distribution. Alternatively, you can create the needed server context by locating and opening the file "conf/server.xml" within the Tomcat distribution using a text editor such as NotePad. For example, within the Host tag for the localhost, place the context tag as follows:

<Host appBase="webapps" name="localhost">
...
<Context path="/Temp" docBase="C:/Windows/Temp"/>
</Host>

If the JSP container is currently running, stop and restart the JSP container so that the new server context will be loaded. Also, if the server context for "Temp dir" has not been defined properly or does not correspond to the system's temporary folder, the process will fail to locate the generated output files.

Note: On some versions of Tomcat, you may need to create the environment variable "CATALINA_HOME" to point to the base directory of the Tomcat distribution as described by the general procedure in the common setup instructions. For example, the environment variable "CATALINA_HOME" might be set to the Tomcat base directory "C:\Program Files\Apache Software Foundation\Tomcat 6.0".

» Back to the Table of Contents. «

Java Server Pages FPWeb Setup

Note: Prior to performing the setup instructions in this section, the instructions in the prior section "Java Server Pages General Setup" need to be performed.

Now that the prior section has setup the Temp alias for generated documents, the FPWeb user directory needs to be created with the proper privileges so that a particular user's query definitions can be stored and subsequently used to generate documents. There are many different ways to structure your user directories, including automatically inheriting privileges into sub-directories. However, we'll just setup the single user directory "FPUser" for the purpose of demonstration.

Note: In order to set the necessary privileges for the default "FPUser" directory, the "Security" tab on the directory properties dialog must be enabled if it's not already visible. To enable the "Security" tab, navigate to your control panel and select "Folder Options". Next, select the "View" tab and scroll to the bottom of the list. Click off (disable) the option "Use simple file sharing" and close the "Folder Options" dialog and the control panel.

From the Windows Explorer, locate the appropriate directory within your JSP container (e.g., "webapps/ROOT") and create a new subdirectory called "FPUser". Right-click on the new FPUser directory and select "Properties". Click on the "Security" tab and select the group "Everyone". (If "Everyone" does not already exist, click the "Add" button to insert the "Everyone" group).

Click on the "Advanced" tab, subsequently select the "Everyone" group from advanced dialog, and press the "Edit" button. Select "Apply to this folder and files, and click on the options "List folder/read data", "Read attributes", "Read extended attributes", "Create files/write data", "Create folders/append data", "Write attributes", "Write extended attributes", "Delete", and "Read permissions". (All other options should be clicked off/disabled.) Finally, close all directory properties dialog boxes. (Note: If the "Delete" option is not enabled, a user will not be able to delete their own query definitions.)

As an option, the supplied FPSample.fpm template uses an image in its header. However to allow this image to show, please create a directory called "Images" under the newly created "FPUser" directory. Then, copy the "FinerEdge.jpg" image from the adjoining directory "FPWebJSP\Images" to "FPUser\Images". (In general, you may want to consider having an "Images" directory under each user directory to allow your users to upload images they may want to see in their generated report headers.) You can also optionally customize the look and feel of FPWeb by updating the FPHeader.htm and FPFooter.htm files.

Important: Copy the entire supplied folder FPWebJSP (in the FinerEdge Publisher installation directory) into the appropriate directory within your JSP container, e.g., "webapps/ROOT", (i.e., at the same level as the newly created FPUser directory). Locate and open (in NotePad or another editor) the file "FPConfig.jsp" within the newly copied FPWebJSP directory. Modify any needed settings to reflect your system's configuration and save the file. (At minimum, you'll need to change "My User" in the variables "strCatalogFile" and "strTemplatePath" to reflect the user name of the system profile where FinerEdge Publisher was installed.)

Note: In a production environment, each user would signon with their own usercode instead of using the default "FPUser". A front-end web page would therefore need to set the session variable "UserName" to the applicable usercode prior to redirecting the user to "FPWeb.jsp". In addition, the sub-directory corresponding to the UserName will need the same folder permissions as was previously outlined for FPUser.

» Back to the Table of Contents. «