Much of the work in developing SilverStream applications involves coding Java. This chapter presents some key things you need to know about Java in this context, including:
Java is a standard language for Web applications and you'll use it in a standard way when developing Web applications to run on the SilverStream Server. For instance, you'll:
SilverStream supports the Java 2 platform, including:
These encompass the core Java language and a variety of Java APIs.
The core Java language is the syntax you use to perform basic programming chores. It includes:
Much of this syntax is modeled after C and C++. JavaScript programmers will find some similarities too (although Java and JavaScript differ in other significant ways).
API is short for application programming interface. In Java, an API is a collection of public classes (in one or more packages) that:
For business programming, where productivity is especially important, you'll always access one or more APIs. For example, the Java standard (J2SE) API provides many of the most fundamental capabilities you'd want to build into any application (including support for: graphical user interfaces, input/output, data type manipulation, threading, networking, security, SQL, internationalization, and a lot more). There's no need to develop these capabilities yourself.
Other Java and vendor APIs (such as the SilverStream API) take you beyond generic application services to fulfill higher level system and business needs.
If you're new to Java or just need to explore a specific Java topic, try the following recommended learning resources.
A practical programming guide covering all the basics of Java, with many working examples
| |
An index to Java learning and reference materials from Sun, with links to many documents and Web sites
| |
Code examples of basic Java techniques you'll commonly use in your SilverStream applications
|
Other books
There are many other Java books available, but some good ones are:
Other Web sites
There are many other Java sites on the Web, but some good ones are:
When building an application, you'll use particular Java APIs depending on the features or services that application requires. To help you choose which APIs you need, Sun has grouped them in different editions of the Java 2 platform:
SilverStream supports the Java APIs as follows.
Java 2 Enterprise APIs>EJB API | ||
Java 2 Enterprise APIs>Servlet & JSP API | ||
Java 2 Enterprise APIs>Servlet & JSP API | ||
Java 2 Enterprise APIs>JavaMail API | ||
Java 2 Enterprise APIs>JAF API | ||
Java 2 Enterprise APIs>Transaction API | ||
Java 2 Enterprise APIs>JDBC Optional API | ||
Java 2 Enterprise APIs>JNDI API | ||
Java 2 Enterprise APIs>RMI-IIOP API |
To implement SilverStream features and services in your application, you can use SilverStream API classes in your Java code and call their methods. The SilverStream API provides public classes (and interfaces) for both the client and server portions of an application, organized into several packages.
The SilverStream API is based on the Java 2 APIs (J2SE and J2EE). That means it includes classes that inherit from Java 2 classes and implement Java 2 interfaces. If you're familiar with the Java 2 APIs, you'll have a good foundation for understanding and using the SilverStream API.
Given the number of packages in the SilverStream API and their various uses, it's helpful to look at them in a couple of different ways:
That way, you can choose the appropriate packages to fulfill your application requirements.
Use the following table to find the packages that provide the major SilverStream features or services you want in your application.
The following table shows which SilverStream packages run on the client tier of an application, which run on the server tier, and which may run on either tier (depending on their use).
NOTE This table reflects the public use of SilverStream API packages. Internally, SilverStream may use some packages in additional ways.
The name SilverStream API refers to all of the public packages. You'll also see the term API applied to certain subsets of these packages. For instance, the name Server Administration API is typically used to refer to this group of packages:
Just remember that these other APIs are simply convenient labels for talking about specific portions of the full API.
SilverStream provides a complete API specification in javadoc format. This specification details all of the packages, classes, interfaces, and members in the public SilverStream API, and includes links into the Java 2 API documentation. It's an indispensable reference for all the SilverStream programming you do in Java.
See this page in the API Reference book in online help: SilverStream API.
You can use the Java development tools of your choice to build SilverStream applications, ranging from code editors to complete IDEs (integrated development environments). If you're using the SilverStream Designer as your IDE, read this section to learn about Java coding in that environment.
The SilverStream Designer supports the full SilverStream API. That means you can use any packages, classes, interfaces, and members from the API when you work in the Designer to build your application.
In addition, the Designer makes it easy to access the SilverStream API. It:
Programming in the SilverStream Designer involves:
The Java coding portion of your work includes editing, compiling, testing, and packaging.
You'll use the Programming Editor to write Java code in the Page Designer, Form Designer, and Business Object Designer. It enables you to use the full Java language, Java APIs, and SilverStream API to write:
The lists on the right enable you to select objects and methods from the SilverStream API to insert in your code. You can also use them to get context help from the SilverStream API reference documentation (by highlighting a list item and pressing F1).
You can write any kind of class (or interface) you need, including those that use only Java APIs and those that use the SilverStream API as well.
The Programming Editor also lets you compile your edited code and save it to the SilverStream Server.
For all the details on working in the SilverStream Programming Editor, see the Programming Editor chapter in the online Tools Guide.
Using an external editor
If you have a favorite editor (such as Codewright) that you prefer to use, you can tell the SilverStream Programming Editor to take you there for your Java code editing:
Then you can return to the SilverStream Programming Editor to compile your edited code and save it to the SilverStream Server.
To learn about setting preferences for the external editor to use, see the Main Designer chapter in the online Tools Guide. For details on launching and accepting changes from your external editor, see the Programming Editor chapter in the Tools Guide.
Importing Java packages
The Programming Editor automatically generates import statements for the most common Java API packages you need in your code. For example, you might see these imports in the code for a page:
import java.awt.*; import java.util.*; import java.math.*; import java.awt.event.*; import java.io.*; import javax.servlet.*; import javax.servlet.http.*;
The specific imports you get depend on the kind of object you're developing. You can add imports yourself for any additional packages you access.
Importing SilverStream packages
Besides generating import statements for Java API packages, the Programming Editor automatically generates imports for SilverStream API packages you need in your code. For example, you might see these imports in the code for a page:
import com.sssw.rt.gui.*; import com.sssw.rt.util.*; import com.sssw.rt.event.*; import com.sssw.rt.expr.*; import com.sssw.shr.page.*; import com.sssw.shr.http.AgiHttpServletRequest; import com.sssw.shr.http.AgiHttpServletResponse; import com.sssw.shr.http.AgoServletException; import com.sssw.srv.api.*; import com.sssw.srv.busobj.*; import com.sssw.srv.mail.*;
Again, the specific imports you get depend on the kind of object you're developing. And, you can add imports yourself for any additional packages you access.
About Simple Actions
Within the Form Designer, the Programming Editor provides a supplementary, high-level coding facility called Simple Actions. This feature is especially for newer programmers who want a quick way to generate application logic without writing detailed syntax.
Under the covers, Simple Actions produce Java code. In fact, you can start with Simple Actions and switch to examine and edit the Java code at any time. Just note that once you alter the Java, you can't switch that code back to Simple Actions.
For more information on switching between Simple Actions mode and Java mode, see the Programming Editor chapter in the online Tools Guide.
To compile any Java code you write in the Programming Editor (or in an external editor), you just need to save your work to the SilverStream Server. You can ask to save directly in the Programming Editor or in the corresponding Designer. The Programming Editor also has a Check Syntax command that looks for compile errors without saving anything.
Compile errors display at the bottom of the Programming Editor window:
For more information on compiling Java code in the SilverStream Designer, see the Programming Editor chapter in the online Tools Guide.
Changing compiler settings
The SilverStream Main Designer lets you edit preferences for several compiler settings. You can specify the Java compiler you want to use, flag and debug options, and the location of the compile cache:
For more information on changing compiler settings, see the Main Designer chapter in the online Tools Guide.
About the compile cache
The compile cache is a local directory where the SilverStream Designer stores source and class files when compiling your Java code. It is typically named compilecache and located in your SilverStream install directory.
The compile cache contains trees of subdirectories for each SilverStream server and database you work on. For instance, here's what was in someone's compile cache for the database Examples3_EJB on the server localhost:
Within the compile cache, you'll find the JAVA and CLASS files for different kinds of objects organized by the packages they're in:
...\com\sssw\gen\forms ...\com\sssw\gen\pages ...\com\sssw\gen\views
The compile cache also includes a source subdirectory named agEditor where the SilverStream Designer stores temporary JAVA files while you're working in an external editor. Whenever you tell the SilverStream Programming Editor to retrieve your externally edited code, it gets that code from here.
Using the compile cache
You can explore the compile cache and read any of the JAVA files it contains. This may be useful when you want more of an inside look into how your application is implemented in SilverStream.
CAUTION! The compile cache is not intended for you to edit. Changes you make there may either be lost or cause unpredictable results.
Compiling multiple files
Sometimes you'll need to compile several files at once. The SilverStream Main Designer provides a Build command that enables you to compile multiple selected files, an entire directory of files, or all files in your application (database). For example, if you use source control to get files edited by someone else, you'll need to build those files.
For more information on doing builds, see the Main Designer chapter in the online Tools Guide.
The most basic way to test the Java code you write is to run particular pages or forms and see if they work as intended. You can do that from the Page, Form, or Main Designer. If you discover or suspect any kind of problem, you can try solving it with one of these additional tools:
Using the SilverStream Debugger
The Debugger helps you find runtime bugs by controlling and monitoring the execution of your Java code. You can debug both client-side code (forms) and server-side code (pages and business objects), either on a local host machine or remotely on distributed machines.
Here's an example of debugging a page on the SilverStream Server that shows how you can:
For more information on debugging, see the SilverStream Debugger chapter in the online Tools Guide.
Using the Java Console
You can use the Java Console to help with your form debugging. It displays System.out and System.err output, including AgfForm.debugPrint() and println() methods, from your client-side code:
The Java Console also displays compile messages. You can start it from the SilverStream Main Designer.
For more information on using the Java Console, see the Main Designer chapter in the online Tools Guide.
Using the Server Console
You can use the Server Console to help with your page and business object debugging. It displays System.out and System.err output, including println() methods, from your server-side code:
The Server Console also displays server debug messages for client requests, business object execution, and database SQL statements (according to what you turn on in the SilverStream Management Console). You can start it from the SilverStream Main Designer.
For more information on using the Server Console, see the Main Designer chapter in the online Tools Guide.
Using the SilverStream Profiler
The Profiler helps you identify and analyze performance bottlenecks in your code caused by inefficient methods, memory leaks, and contended monitors in synchronized processes. You can invoke the Profiler by supplying a command-line option when starting a SilverStream executable (such as SilverServer.exe), then use it to study processes running in that context.
For more information on profiling, see the SilverStream Profiler chapter in the online Tools Guide.
To organize the business objects and utility classes you develop, you typically put them into packages. The Main Designer enables you to create packages and create objects in them (by going to the Business Object Designer).
The following example shows classes and interfaces that someone has created in their own package hierarchy:
com.examples.companydemo
While editing the code for an object, you can alter its package statement (and then save) to copy that object to a different package:
For more information on creating packages, see the Business Object Designer chapter in the online Tools Guide. To learn more about editing package statements, see the Programming Editor chapter in that guide.
NOTE Packaging for forms, pages, and views is controlled by the SilverStream Designer. You don't specify your own packages for them.
Using JAR files
It's also common to bundle packages, classes, and other application files into JAR files. JARs are standard Java archive files used to support deployment (for JavaBeans, Enterprise JavaBeans, and JavaServer Pages), downloading (for files used by forms on the client), and dynamic references (to classes from other SilverStream databases).
The Main Designer enables you to create JARs and go to the JAR Designer to edit their details. It also lets you upload externally created JARs that you want to use on the SilverStream Server for your applications.
Here's a JAR named CompanyDemo.jar that someone has defined in the JAR Designer to contain the package com.examples.companydemo:
For more information on working with JAR files, see the JAR Designer chapter in the online Tools Guide and
Using Utility Classes, JAR Files, and JavaBeans in the Programmer's Guide.
You might already have a Java development environment that you like to work in--either a third-party code editor (such as Codewright) or complete IDE (such as JBuilder or Cafe). In that case, you may choose to build your SilverStream applications there, without using the SilverStream Designer.
Read this section to learn about accessing the SilverStream API and writing SilverStream classes when working in an external Java development environment.
From an external development environment, you have access to a large subset of the SilverStream API. You can use the packages, classes, interfaces, and members that the API provides for coding:
See
Writing Session Beans and
Triggered Object Basics
See
Writing Entity Beans and
Using Data Source Business Objects
See
Writing External Java Clients
See the chapter on using the Server Administration API in the Administrator's Guide
What's not supported
Not supported in external development are the parts of the API used exclusively for SilverStream pages, forms, and views. This is mainly because the API itself doesn't include everything required to completely define these objects. You need to use the SilverStream Designers to do that before you can start writing API code.
The following table lists the SilverStream API packages supported for external development, organized by the function each performs. Use it to find the packages that provide the major SilverStream features or services you want in your application.
For those SilverStream packages supported for external development, the following table shows which ones run on the client tier of an application, which run on the server tier, and which may run on either tier (depending on their use).
NOTE This table reflects the public use of SilverStream API packages. Internally, SilverStream may use some packages in additional ways.
Before you can code and compile a SilverStream application in an external Java development environment, you must set up that environment to access the SilverStream API packages. This involves:
To learn how to set up if you're using one of the SilverStream integrations for external IDEs, see the online Using External IDEs book.
To learn about setting up deployed Java client applications to access the SilverStream packages they need, see
Writing External Java Clients.
To access the SilverStream packages, your development environment requires the ZIP and JAR files from SilverStream that contain those packages as well as some supporting Java and third-party packages (including JBroker).
The recommended way to get all of these files is to install the SilverStream Server on your local development machine. (You'll typically want to have a local server anyway, for testing and debugging your externally written SilverStream applications.)
For instructions on installing the SilverStream Server, see the Installation Guide.
Once you've installed, you need to make sure your development environment can find the ZIP and JAR files that contain the SilverStream and supporting packages. You can do that by setting your classpath to list these files.
There are several ways to set the classpath, including:
CLASSPATH environment variable for your system
-classpath command-line argument when running the Java compiler
Choose the way that's most appropriate for how you work and the tools you use.
Listing the SilverStream files
The following table shows the SilverStream ZIP and JAR files you need to list on your classpath. You'll list one or more of these, depending on the kinds of classes you're developing.
Listing the Java and third-party files
The following table shows the other supporting ZIP and JAR files you need to list on your classpath. It's recommended that you always list all of these.
Compiler troubleshooting
If you have trouble compiling classes for your SilverStream application, you should check that:
You'll generally want to include import statements for the SilverStream packages you use in your code. For example:
import com.sssw.rt.util.*;
That way, you won't need to fully qualify the names of SilverStream API classes you reference. Almost all of those classes follow a unique naming convention (beginning with Ag), so you shouldn't normally encounter naming conflicts when omitting package qualifiers.
No matter which external Java development environment you use, you'll perform the following steps to build SilverStream applications.
To code your classes, you'll use:
You can start help from your operating system by using the SilverStream Help icon in the SilverStream program group (if available). Then see this page in the API Reference book: SilverStream API.
To compile your classes, you'll use:
See
Setup requirements.
To import your server classes, you'll use:
See the SilverCmd reference chapter in the online Tools Guide.
See the online Using External IDEs book.
To test how your classes work when the application runs, you'll use:
See the SilverStream Debugger chapter in the online Tools Guide.
See the Administrator's Guide.
See the SilverStream Profiler chapter in the online Tools Guide.