Core Development Guide
|
|
Core Development Guide |
This chapter gives an overview of how to access Director services programmatically. It contains the following sections:
To write Java code for Director applications, you use Director API classes in your Java code and call their methods. The Director API provides public classes (and interfaces) organized into several packages, which themselves are organized by subsystem.
The Director 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 Director API.
Java is a standard language for Web applications and you'll use it in a standard way when developing Director applications. For instance, you'll:
Write classes that represent the objects in your application, including fields (variables) for each object's data and methods for the actions it can perform
Organize classes in packages, directory-like hierarchies that let you group related classes and make them easy to locate
Bundle packages and classes in JARs (and other archive files), used for providing smaller, faster downloads to clients and for facilitating certain deployment operations
Director 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:
Offers a reusable solution for implementing a particular area of application features or services
Defines public methods you can call (and possibly public fields you can access)
Provides a published specification (typically in javadoc format)
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 Director 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.
Books There are many other Java books available, but some good ones are:
Core Java by Cay S. Horstmann and Gary Cornell, published by Prentice-Hall
Java in a Nutshell by David Flanagan, published by O'Reilly & Associates
Teach Yourself Java 2 in 21 Days by Laura Lemay, published by Sams
The Java Programming Language by Ken Arnold and James Gosling, published by Addison-Wesley
Web sites There are many 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:
J2SE includes the standard API that serves as the foundation for virtually any Java application you build.
J2EE includes several APIs for adding specific enterprise-level features and services to a Java application, including:
Once you're familiar with the basics of Java (including the core language and J2SE API), you can learn about J2EE and its use from the following resources.
|
Resource |
Description |
|---|---|
An index to J2EE learning and reference materials from Sun, with links to various documents and Web sites | |
Both of these resources are available at java.sun.com.
The Director API provides public classes and interfaces organized into several packages, which themselves are organized by subsystem.
Use the following table to find the packages that provide the major Director features or services you want in your application.
|
Functional area |
Packages |
|---|---|
The name Director 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 Content Management 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.
Director provides a complete API specification in javadoc format. This specification details all of the packages, classes, interfaces, and members in the public Director 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 the API Reference book in online help for complete reference information on the Director API.
To access the services of a Director subsystem, you first need to use a factory to get a reference to a manager object for the subsystem. You can do this in one of the following ways:
When you use a delegate, you do not need to know or care whether the service is using a local manager object or a remote object. Therefore, in most situations, you should use delegates to access subsystem services.
Each subsystem provides one or more factory classes called EboFactory that are suitable for accessing manager objects for the subsystem.
Once you have a reference to the manager object, you can call methods on that object just as you would call methods on any Java class.
Several Director subsystems let you use delegates to access subsystem services. A delegate is a wrapper that hides the location of a service. The delegate model follows the J2EE Business Delegate pattern.
When you use a delegate, you do not need to know or care whether the service is using a local manager object or a remote object. The delegate initially attempts to instantiate a local manager. If this fails, it attempts to use the remote object instead. This approach allows developers to use the same code on clients and servers to instantiate services.
Director provides one or more delegates per manager. For example: the Content Management subsystem has a single delegate, but the User subsystem has four delegates (User, Group, UserMeta, and UserPersonalization).
To use a delegate to access a subsystem service, you need to call a delegate accessor method on the custom EboFactory class for the subsystem you want to use. The EboFactory class that has the method you need is typically located in the subsystem package hierarchy in a subpackage called client.
The delegate model is supported by the following subsystems:
Examples For example, to use the Content Management delegate to access content management services, you might execute this code:
import com.sssw.cm.api.*; ... EbiContentMgmtDelegate contentMgr = com.sssw.cm.client.EboFactory.getDefaultContentMgmtDelegate(); ...
Once you have a reference to the delegate, you can call simply invoke methods on the delegate. Here's an example that shows how you might do this from a component:
EbiDocument tempdoc = contentMgr.getDocument(context,selectedDoc);
Similarly, to use the User delegate to access User subsystem services, you might execute this code:
import com.sssw.fw.usermgr.api.*; ... EbiUserDelegate userMgr = com.sssw.fw.usermgr.client.EboFactory.getUserDelegate(); EbiUserInfo userinfo = userMgr.createUser(context); ...
Using a delegate to access a local manager The delegate initially attempts to instantiate a local manager. If this fails, it attempts to use a remote object instead. This approach can mask errors on an attempt to use a local manager only. To help you identify situations where the local instantiation fails, the delegate constructors display an informational message in the log when an instantiation fails.
You can also force the delegate to use a local manager only by using a parameterized delegate factory constructor. To do this, you pass in a string indicating that you want a local delegate only. The EbiDelegate interface provides a constant you can use to indicate that you want a local delegate. If the constructor fails, it will not swallow the instantiation error on the local manager. Here's an example.
import com.sssw.fw.api.*; ... EbiUserDelegate ud = com.sssw.fw.usermgr.client.EboFactory.getUserDelegate(EbiDelegate.SERVICE_LOCAL);
Some of the Director subsystems provide a way to get a manager object directly. For example, the EboFactory class for the portal subsystem (com.sssw.portal.factory.EboFactory) has several methods you can use to get manager objects:
For example, to get a reference to the component manager from a component, you might use this code:
import com.sssw.portal.api.*;
...
import com.sssw.portal.factory.*;
public void getComponentData( com.sssw.portal.api.EbiPortalContext context, java.util.Map params ) throws com.sssw.fw.exception.EboUnrecoverableSystemException {
StringBuffer sb = new StringBuffer();
com.sssw.portal.api.EbiComponentConstants.MIME_TYPE_HTML_UTF8 );
// build up the component return data, buffers are best
EbiPortalComponentInfo compinfo = null;
try {
EbiComponentManager compmgr = EboFactory.getComponentManager(context);
compinfo = compmgr.getComponentInfo(context,"tbattleComponent1", true);
}
catch (com.sssw.fw.exception.EboFactoryException e)
{
}
String category = compinfo.getComponentCategory();
sb.append(category);
// place the content into the context
context.setComponentContent( sb.toString() );
}
}
Some of the subsystems for which delegates are provided also support direct access to manager objects. This support can be used in situations where the subsystem is running locally. For example, you can use the getUserManager() method to access the manager object for the User subsystem directly. Here's how you might do this in a portal component:
import com.sssw.fw.usermgr.api.*;
import com.sssw.fw.usermgr.client.*;
...
public void getComponentData( com.sssw.portal.api.EbiPortalContext context, java.util.Map params ) throws com.sssw.fw.exception.EboUnrecoverableSystemException {
StringBuffer sb = new StringBuffer();
context.setContentType( com.sssw.portal.api.EbiComponentConstants.MIME_TYPE_HTML_UTF8 );
EbiUserManager usermgr;
String fname="";
try {
usermgr = EboFactory.getUserManager();
try {
EbiUserInfo userinfo = usermgr.getUserInfoByUserID(context,
"tbattle");
fname = userinfo.getUserFirstName();
}
catch (com.sssw.fw.exception.EboSecurityException e)
{
}
}
catch (com.sssw.fw.exception.EboFactoryException e)
{
}
sb.append("First name is " + fname );
// place the content into the context
context.setComponentContent( sb.toString() );
}
The Rule subsystem requires that you use a different technique to get a manager. The Rule subsystem allows you to work with multiple rule manager instances—unlike the other subsystems, which only allow you to have a single manager instance. Therefore, to use a rule manager, you need to instantiate the object. Here's how you might do this in a portal component:
public void getComponentData( com.sssw.portal.api.EbiPortalContext context, java.util.Map params ) throws com.sssw.fw.exception.EboUnrecoverableSystemException {
StringBuffer sb = new StringBuffer();
com.sssw.portal.api.EbiComponentConstants.MIME_TYPE_HTML_UTF8 );
// build up the component return data, buffers are best
EbiRuleManager rm;
String myRule="MyRule";
String phrase="";
try {
rm = EboFactory.createRuleManager();
com.sssw.re.api.EbiContext ctx =
com.sssw.re.factory.EboFactory.createEbiContext(
context.getEbiRequest().getHttpServletRequest(),
context.getEbiResponse().getHttpServletResponse(),
context.getServletContext());
com.sssw.re.api.EbiContext rectx = rm.fireRule(myRule, ctx);
phrase = rectx.getResponsePhrase();
}
catch (com.sssw.fw.exception.EboFactoryException e)
{
}
sb.append( phrase );
// place the content into the context
context.setComponentContent( sb.toString() );
}
|
|
Core Development Guide |
Copyright © 2002, SilverStream Software, Inc. All rights reserved.