7.1. Installing the Application
- User inserts the installation CD ROM into the CD drives.
- User opens the Windows Explorer.
- User click-and-drags the \<Application> folder from the CD Rom to the desired base directory (e.g., D:\).
- System copies all the files to the installation folder.
- Note: subsequently, the directory the Application is installed in is referred to as the Application home directory (e.g., D:\Application).
7.1.1. Defining the Application Web Site
The <Application home>\dist directory contains the files that are required to be distributed (deployed) in order to run the application. This folder must be published to IIS before clients can access the deployment files. The simplest way to publish the direct is by Web Sharing it as follows:
- User opens the Windows Explorer.
- User opens the properties of \Framework\dist
- System presents the dist Properties dialog.
- User selects the Web Sharing tab.
- User presses the Add button.
- User enters MyWeb as the alias.
- User presses the OK button.
- System adds the alias MyWeb to the Default Web Site.
7.1.2. Enabling Anonymous Access to the Application Web Site
Before the client can use Web Start, the administrator must ensure that anonymous access is enabled on the web site. This is necessary or Web Start will not be able to download the required resources as it is unable (in it current implementation) to negotiate the MS security.
- User opens the Internet Information Services management console (as described above).
- User opens the Default Web Site properties (as described above).
- User selects the Directory Security tab.
- User presses the Edit button under the Authentication and access control group.
- User ensures the Enable anonymous access check box is checked.
7.2. Deploying the Application
This procedure can be used to deploy a new version of the application.
Acquire a new version of the application from fdata. Typically, this will be distributed as a single zip file.
Unzip the Application Zip File
Verify Web Start Configuration
Edit .JNLP and ensure:
- codebase=”http://:8888//”
Verify Client properties Configuration
Edit .properties and ensure:
- FServer.isDeployed = true
- FServer.hostname =
Verify server properties Configuration
Edit .server.properties.
- FDatabaseManager.url = jdbc:oracle:thin:@:1521:orcl
If performance needs to be monitored:
- FDatabaseManager.explainPlans = true
- FDatabaseManager.explainPlanThreshold = 1000
Verify Wrapper Configuration
Edit wrapper.conf and ensure:
- wrapper.java.command= \bin\java – ensure version is consistent with client version
- wrapper.java.additional.2=-Dcom.foundation.widgets=10000
- wrapper.java.maxmemory=1024
- wrapper.java.library.path.1=. – essure this is a path to wrapper.dll
Verify Home Page Configuration
Verify version of java referenced for download is the same as the version the server is using
Install the Service
From the command line using an admin account:
- wrapper -i wrapper.conf
Checking the Services
The following services must be started:
- Server – application service
- OracleOraDb10g_home1TNSListener – oracle’s TNS listener
- OracleServiceORCL – oracle database manager
All of these services are currently running and are configured to automatically start using the local system account.
7.3. Configuring the Application
Each Application can be configured using a wide variety of configuration properties that apply to presentation, deployment, security, logging, etc… Each Application has two application-specific property files: one for server configuration and one for common configuration (including client, common, and server). All properties used by an application are set based on the values contained within the default property file (framework.properties) and then specialized using the application-specific property files.
The default configuration file as specified by Framework can be found within the \Framework\classes:
The framework.properties file defines the default properties for all applications. Typically, this includes:
- client configuration (e.g., proxy, enabling anti-aliasing, font size/name/style, enabling tool tips, max login attempts, enabling button labels, desktop height/width, file chooser height/width, label prefix/suffix, panel layout, table box selection color, table panel size)
- common configuration (e.g., date/time format, log severity level, enabling component tracking, model import/export paths, document path, phone number format, retry settings)
- service configuration (database manager class, database url, enabling explaining plans, database username (code) and password, security manager keystore, mode of execution (deployed/standalone), email SMTP server, enabling service components tracing, server-side auditing, etc.).
The application specific configuration files can be found within <application home>\classes:
The <application>.properties file defines the common properties specific to an application. Typically, these properties are specified to override the framework.properties client/common configuration settings with application-specific values. The following property should be configured if the Application Server is behind a firewall:
- FServer.proxy
The <application>.server.properties file defines the properties specific to an application’s server configuration. Typically, these properties are specified to override the framework.properties service configuration settings with application-specific values. The following property should be configured if the Database Server is located on a separate server:
- FDatabaseManager.url
7.3.1. Configuring Secured Transport
The process of configuring an application to enable secured transport (Secure Socket Layer (SSL/TLS)) is somewhat complex; however, this is the nature of the PKI security. Several steps are involved that must be followed very carefully, and there is a degree of maintenance involved due to the nature of certificate expiry.
On the server, in the distribution folder, create a server keypair and store this keypair in a password-secured keystore:
keytool -genkey -alias <App>Server -keyalg RSA -keystore keystore
Enter keystore password: <password>
Re-enter new password: <password>
What is your first and last name?
[Unknown]: <your name>
What is the name of your organizational unit?
[Unknown]: <your organization unit>
What is the name of your organization?
[Unknown]: <your organization>
What is the name of your City or Locality?
[Unknown]: <your city>
What is the name of your State or Province?
[Unknown]: <your state/province>
What is the two-letter country code for this unit?
[Unknown]: <your country code>
Is … correct?
yes
Export the cert (self-signed public key) of the <App>Server keypair:
- keytool -export -alias <App>Server –keystore keystore -rfc -file <App>Server.cer
- Enter keystore password: <password>
- Certificate stored in file <App>Server.cer
Create a truststore (jssecacerts) that trusts the server cert:
- keytool -import -alias <App>Server –file <App>Server.cer –keystore jssecacerts
- Enter keystore password: <password>
Owner: CN=kv, OU=IT, O=ABC, L=KC, ST=MO, C=US
Issuer: CN=kv, OU=IT, O=ABC, L=KC, ST=MO, C=US
Serial number: 42fc999e
Valid from: Fri Aug 12 07:44:14 CDT 2005
until: Thu Nov 10 06:44:14 CST 2005
Certificate fingerprints:
MD5: 08:09:5D:2C:4B:28:D9:94:48:69:6D:AE:8E:
B2:43:CB
SHA1: 14:BE:5F:88:1F:8D:2D:04:93:F6:22:02:84:
C0:DD:51:4F:B0:E8:97
Trust this certificate? [no]: y
Certificate was added to keystore
On each client that needs to communicate with the server:
- Copy the truststore (jssecacerts) file to the <Java Home>/lib/security folder. If you aren’t sure where the Java home is, the client will log its location when it is started using JNLP and is visible from the Java debugging console.
Configure the application properties:
- FSecurityManager.useSSL = true
Configure the application server properties:
- FSecurityManager.keystoreFileName = keystore
- FSecurityManager.keystorePassword = <password>
Note
- The server’s keystore should be secured such that only the account that the application service is running under has access to it. This file should NOT be publically visible through the web server.
- The client-side truststore must be called jssecacerta (with no file extension) for JVM’s Secure Socket Extensions (SSE) to find it.
- Eventually, the server’s keypair (and the corresponding cert) will expire and need to be re-generated. The truststore (jssecacerts) will also need to be recreated and deployed on all clients.
- If the JVM on the client is upgraded such that it is now located in a new folder, the truststore (jssecacerts) will need to be re-copied to the new folder.
- An alternative approach to using an self-signed certificates is to use a signed cert for the server; typically, this involves purchasing an SSL/TSL enabled cert from a certificate authority (CA). The CA must be one of the root CAs already defined in Java’s cacerts truststore. This removes the need to deploy the truststore to the clients and to update it when the server’s cert expires or a new JVM version is installed.
If required, enabling tracing and debugging:
- Add the following JVM argument: -Djavax.net.debug=all
7.4. Defining the Application Database
Before clients can access the application, the database schema must be defined and test data must be loaded. This can be accomplished by starting the application in server mode with the define option specified.
Administrator starts the application in define mode. From a command window, in the <Application home>\dist directory, execute:
- run -define
- System presents the Database Definition window.
- Administrator follows the scenario Creating the Schema as detailed below.
7.4.1 Creating the Schema
User presses the Create All button.
System creates all database schema objects required by the application and loads the test data. This includes creating the schema, defining all object types, object tables (including constrains and identifiers), object views, and adding constraints.
7.4.2. Recreating Schema and Reloading Test Data
During development, it is often desirable to re-create the database schema. Typically, this becomes necessary when one-or-more of the underlying framework classes are changed.
- User selects the root business class (Object is selected by default).
- User presses the Recreate button.
- System drops all database schema objects and then defines them for the selected root class (and all of its subclasses).
- System loads all test data into the database tables.
7.4.3. Custom Definition Operations
- User selects the root business class that the operations are to be performed on using the tree control.
- User selects which definition options should be performed in the Definition Options group box.
- User presses Define button.
- System performs the specified operations. Operations are performed in the following order: drop-user, delete-data, drop-views, drop-table-views, drop-tables, drop-type, drop-indexes, create-user, create-types, create-tables, create-table-views, create-views, insert-data, and create-indexes.
7.5. Starting the Application Service
Before client workstations can access the application, the application service must be started on the application server.
Administrator starts the application service. From a command window, in the <Application home>\dist directory, execute:
- run -server
- System starts the application in ‘server’ mode.
7.6 Starting a Test Application Client
Once the application service is running, an application client can be started.
Administrator starts the application client. From a command window, in the <Application home>\dist directory, execute:
- run -client
- System starts the application in ‘client’ mode and user can follow the Logging In scenario as detailed in the User’s Guide.
7.6.1. Java Web Start
Java Web Start is a helper application that gets associated with a Web browser. When a user clicks on a link that points to a special launch file (JNLP file), it causes the browser to launch Java Web Start, which then automatically downloads, caches, and runs the given Java Technology-based application. The entire process is typically completed without requiring any user interaction, except for the initial single click.
From a technology standpoint, Java Web Start has a number of key benefits that make it an attractive platform to use for deploying applications:
- Java Web Start is built exclusively to launch applications written to the Java 2 SE platform. Thus, a single application can be made available on a Web server and then deployed on a wide-variety of platforms, including Windows 98/NT/2000/ME/XP, Linux, and the SolarisTM Operating Environment. The Java platform has proven to be a very robust, productive, and expressive development platform, leading to a significant cost savings due to minimized development and testing costs.
- Java Web Start supports multiple revisions of the Java 2 platform, Standard Edition. Thus, an application can request a particular version of the platform it requires, such as J2SETM 1.4.0. Several applications can run at the same time on different platform revisions without causing conflicts, and Java Web Start can automatically download and install a revision of the platform if an application requests a version that is not installed on the client system.
- Java Web Start allows applications to be launched independently of a Web browser. This can be used for off-line operation of an application, where launching through the browser is often inconvenient or impossible. The application can also be launched through desktop shortcuts, making launching the Web-deployed application similar to launching a native application.
- Java Web Start takes advantage of the inherent security of the Java Platform. Applications are by default run in a protective environment (sandbox) with restricted access to local disk and network resources. It allows the user to safely run applications from sources that are not trusted.
Applications launched with Java Web Start are cached locally; thus, an already-downloaded application is launched on par with a traditionally installed application.
The technology underlying Java Web Start is the Java TM Network Launching Protocol & API (JNLP). This technology is currently under development via the Java Community Process (JCP). Java Web Start is the reference implementation (RI) for the JNLP specification. The JNLP technology defines, among other things, a standard file format that describes how to launch an application called a JNLP file.
7.6.1.1. Java
Install Java 1.6.0 into the workstation. The latest version can be downloaded from:
7.6.1.2. Application
Using a web browser go to http://<servername>:<port>/<app name>/
Where:
- Servername is the name of the web server
- Port is the port on which the web server runs
- App Name is the web service alias
Click on the link to the <app name>.jnlp file.
The application now starts up, login as the users username, default password is ‘password’.
7.6.1.3. Debugging on the Client
In order to debug the application from the user’s workstation or client the Java Console needs to be displayed.
7.6.1.3.1 Windows
From the user’s workstation open the Control Panel, then double click on the Java applet.
This will open up the Java Control Panel.
Select the Advanced tab.
Expand the Java console branch.
Select the Show console radio button.
Press OK when done.
Now when the application is started a second window “Java Console” will also be started.
All error messages and stack traces will be outputted to this window.
7.7. Stopping the Application Service
- Administrator closes the command window that was opened when they started the application service.
- System shuts down the application service.
7.8. Monitoring the Application
Java provides a console that can be used to monitor Java applications using jmx technology. The application must be started with the following jvm parameters:
- Dcom.sun.management.jmxremote.port=<port>
- Dcom.sun.management.jmxremote.ssl=false
- Dcom.sun.management.jmxremote.authenticate=false
Note: the default port used by JMX conflicts with the default RMI port used by Framework; therefore, it is recommended an alternate port (e.g., 9999) be used.
Once the application server is started, the console can be started by running jconsole.exe from the java bin directory. A remote connection must then be opened that specified the hostname (e.g., localhost) and port (e.g., 9999).
The console monitors the following aspects of the application: memory, threads, classes, beans, and the Java virtual machine (VM).
7.9. Configure the Email Integration
Edit the <app name>.server.properties file in the project directory and set the FEmailManager.smtpServerName, FEmailManager.senderMailAddress and FEmailManager.footer:
- FEMailManager.smtpServerName = <SMTP Server>
- FEMailManager.senderMailAddress = <Sender Email>
- FEMailManager.footer = <message>
Where:
- SMTP Server is the name of the local mail server on the network that can forward email sent from the application server.
- Sender Email is the email address that the users will see in the from field of the email.
- Message is the message to go at the footer of the email. Usually the name of the application.
7.10 Configure Help
Edit the <app name>.properties file in the project directory and change the FModel.docURL parameter to the web server:
- FModel.docURL = http://<servername>:<port>/<app name>/doc
Where:
- Servername is the name of the server that is running Apache
- Port is the port on which the web server runs, usually 80
7.11. LDAP Authentication
7.11.1. OpenLDAP Configuration
Edit the <app name>.properties file in the project directory and change the FSecurityManager.authenticator to LDAP:
FSecurityManager.authenticator = LDAP
Edit the <app name>.server.properties file in the project directory and add/change the following properties:
FLDAPManager.type = LDAP
FLDAPManager.hostname = localhost
FLDAPManager.port = 389
FLDAPManager.securePort = 636
FLDAPManager.useSSL = false
FLDAPManager.mechanism = simple
FLDAPManager.usersOrgUnit = <Users Organizational Unit> ie. ou=staff,dc=foundationdms,dc=com
FLDAPManager.defaultUserRole = GUEST
FLDAPManager.userNameTag = uid
FLDAPManager.commonNameTag = cn
FLDAPManager.firstNameTag = givenName
FLDAPManager.lastNameTag = sn
FLDAPManager.employeeNumberTag = employeeNumber
FLDAPManager.eMailTag = mail
FLDAPManager.className = com.fbs.service.FLDAPManager
FLDAPManager.autoSyncPeriod = 3600
FLDAPManager.fPersonClassName = com.fbs.common.classes.FEmployee
Anonymous users will need to be able to read the directory. Permissions should be set as in the slapd.conf
access to *
by * read
7.11.2 Active Directory Authentication
Edit the <app name>.properties file in the project directory and change the FSecurityManager.authenticator to LDAP:
FSecurityManager.authenticator = LDAP
Edit the <app name>.server.properties file in the project directory and change set the following properties:
FLDAPManager.type = ActiveDirectory
FLDAPManager.hostname = <Active Directory Server IP>
FLDAPManager.port = 389
FLDAPManager.domain = <Domain for the Users>
FLDAPManager.usersOrgUnit = <Org Unit for Users>
FLDAPManager.userSearchFilter = <Search filter for Users to Sync>
FLDAPManager.roleCommonName = <Group for Users to Sync>
FLDAPManager.adminPrincipal = <user account to access AD>
FLDAPManager.adminPassword = <password to access AD>
7.12 Email Notifications
Edit the <app name>.server.properties file in the project directory and change set the following properties:
FTaskManager.emailOverdueNotifications = false
FATaskManager.emailOverdueNotifications = true
FATaskManager.runTime = 5:00
This sets the email to be sent at 5am.
7.13 Install the Service on LInux
As root copy the fdata script into /etc/init.d and make it executable.
Run chkconfig on the files to setup the correct run levels.
chkconfig fdata add
Reboot the server. It should now automatically start the application.
7.14 Start the Service on Linux
From a terminal window run:
/etc/init.d/fdata start
To stop run the following:
/etc/init.d/fdata stop
7.15 Sync with LDAP
Open a console window to go to the project directory and run the following (make sure the service is not running):
sh ./run.sh –define
Click on the Sync with LDAP button.
7.16 Changing the Admin Password
The admin user is the only user who can change their password from within the application when LDAP authentication is turned on.
Login as the admin user and go to Security -> Change Password.
Enter the old password and the new password twice. Press Execute when done.
7.17 Debugging the Server
All error messages that are generated by the server are logged in the <app name/logs/log.txt file.
This file is over written each time the server is restarted, therefore it is recommended that the file be renamed prior to restarting the service.