Documentum Developer Program

BOF Component Development Guidelines

March 2004

Developer Program
Component Exchange 1/18
Preface
Documentum engineers have gained considerable experience over the years developing
reusable business objects for our client applications. In an effort to capture lessons
learned from this experience, several key engineers collaborated to produce a collection
of best practices and guidelines for business object development. These are now used
internally by all Documentum engineers when developing and unit testing business
objects.
We are pleased to make this development guide available to our developer community.
Please remember that the goal is to facilitate component reuse, extendibility, and quality;
they are not intended to be an exhaustive list of requirements.
Organization of this Guide
The guide starts with checklists that you can use for BOF components with links to a
more detailed guidelines section later in the guide. There are also supporting sections
containing definitions of BOF components and a list of other sources of information.

Developer Program
Component Exchange 2/18
Table of Contents
Preface.............................................................................................................................. 2
Organization of this Guide ............................................................................................. 2
Table of Contents.............................................................................................................. 3
Checklists.......................................................................................................................... 4
BOF Component Checklist ............................................................................................ 5
General Guidelines ........................................................................................................... 8
Audience........................................................................................................................ 8
How to be used.............................................................................................................. 8
Definitions and Overview of BOF Components................................................................. 8
BOF Component Definitions and Overview................................................................... 8
Service-Based Object (SBO) ..................................................................................... 8
Type-based Object (TBO).......................................................................................... 8
BOF Component Guidelines ............................................................................................. 9
What Constitutes a Good BOF Component? ................................................................ 9
Environmental Friendliness ........................................................................................... 9
[BOF-LOG] Logging ................................................................................................... 9
[BOF-TRANSX] Transactions ................................................................................... 9
[BOF-SESS] Session Manager............................................................................... 10
BOF-VERS Versioning Support................................................................................... 10
IDfBusinessObject Methods..................................................................................... 10
Design .........................................................................................................................11
[BOF-SBO] SBO design........................................................................................... 11
[BOF-TBO] TBO design ........................................................................................... 15
[BOF-EXCEP] Exceptions........................................................................................ 15
[BOF-CONV] BOF Conventions/Standards ............................................................. 16
[BOF-DOC] Documentation......................................................................................... 17
[BOF-DOC-01] Javadocs exist for interfaces........................................................... 17
[BOF-DOC-02] TBO Docbase type definition documented...................................... 17
[BOF-DOC-03] Transaction environment expectations documented....................... 17
[BOF-DOC-04] Transaction behavior documented.................................................. 17
[BOF-DOC-05] Component dependencies documented ......................................... 17
[BOF-DOC-06] Supported "features" documented .................................................. 17
[BOF-DOC-07] Version (in)compatibilities documented .......................................... 17
[BOF-DOC-08] Customization hooks documented .................................................. 17
[BOF-DOC-09] Java Runtime Requirements........................................................... 17
[BOF-DOC-10] Known issues documented ............................................................. 18
[BOF-DOC-11] License terms documented ............................................................. 18
[BOF-DOC-12] (Optional) Support and contact info documented............................ 18
[BOF-DEPLOY] Deployment ....................................................................................... 18
[BOF-DEPLOY-01] Jars, not classes....................................................................... 18
[BOF-DEPLOY-02] Implementation/interface jars separate .................................... 18
[BOF-DEPLOY-03] Native code prohibited.............................................................. 18
Client Use of BOs ........................................................................................................ 18
Key Documents/References ........................................................................................... 18
General........................................................................................................................18
BOF-specific ................................................................................................................ 18

Developer Program
Component Exchange 3/18
Checklists
The BOF component checklist has the following columns:
• Category
This column names the general category into which the checklist item fits.
• Checklist item
• Impact
This column rates how critical the checklist item is to the success of the
component. The ratings are:
High – not following this item will lead to lack of reusability, buggy behavior,
inability to migrate, failure of the component to run, and so on
Medium – not following this item will impact the success of the component but
will not cause disastrous consequences
Low – this item may be a best practice or may facilitate the reuse of the
component but will not affect the success of the component itself
• Significance
This column provides a domain for the impact. For example, “Reuse” indicates
that not following this checklist item will impact the ability of this component to be
reused.
• Followed Y/N
This column is the place for you to check off whether you have followed the
checklist item or not.
• Justification if ignored
This column allows you to write a justification of why a particular checklist item
has not been followed.
Note: All checklist items are considered mandatory unless noted as a best practice.

Developer Program
Component Exchange 4/18
BOF Component Checklist
See the section “BOF Component Definitions and Overview” for a definition and general
guidelines on BOF components.
Note: All items are required unless labeled “Best Practice.”
Category Item Impact Significance Followed Justification
Y/N if ignored
Logging
BOF-LOG-01 Used DfLogger for H Reuse
logging

Category Item Impact Significance Followed Justification

Y/N if ignored
Transactions
BOF-TRANSX-01 Used only Session H Reuse
Manager-based
Transactions
BOF-TRANSX-02 No nested transactions H Reuse
BOF-TRANSX-03 Checked whether there is H Reuse
an existing transaction
before creating a new
one
BOF-TRANSX-04 Used Session Manager M Reuse
to simulate synchronized
cross-docbase commits

Category Item Impact Significance Followed Justification

Y/N if ignored
Session Manager
BOF-SESS-01 Used Session Manager H Reuse
BOF-SESS-02 Acquired and released H Reuse
sessions within methods
BOF-SESS-03 Returned created objects H Reuse
correctly
As object id
Adopted by session
manager

Category Item Impact Significance Followed Justification

Y/N if ignored
Versioning Support
BOF-VERS-01 Implemented H Reuse
IDfBusinessObject
methods diligently

Developer Program
Component Exchange 5/18
Category Item Impact Significance Followed Justification
Y/N if ignored
SBO Design
BOF-SBO-01 Planned for extensibility M Extendibility
without language
extension
(1) Composition
(decorator)
(2) Hooks (strategy)
BOF-SBO-02 Methods use interfaces H Extendibility
rather than concrete
classes
BOF-SBO-03 Preferred DFC interfaces H Extendibility
to Java library interfaces
or classes
BOF-SBO-04 Used IDfId to pass H Extendibility
objects as arguments in
interfaces

Category Item Impact Significance Followed Justification

Y/N if ignored
TBO Design
BOF-TBO-01 Anticipated dynamic H Extendibility
inheritance
BOF-TBO-02 Class implementing H Extendibility
IDfDynamicInheritance is
the class whose
superclass is to be
replaced
BOF-TBO-03 TBO interface avoids M Extendibility
unnecessary inclusion of
IDf<base> methods
BOF-TBO-04 New functionality M Extendibility
wrapped in SBO facade

Category Item Impact Significance Followed Justification

Y/N if ignored
Exceptions
BOF-EXCEP-01 Throws only DfException M Standards
and domain exception
base class
BOF-EXCEP-02 Avoided Subclassing M Standards
DfException wherever
possible

Developer Program
Component Exchange 6/18
Category Item Impact Significance Followed Justification
Y/N if ignored
Conventions/Standards
BOF-CONV-01 Followed naming L Reuse
conventions

Category Item Impact Significance Followed Justification

Y/N if ignored
Documentation
[BOF-DOC-01] Javadocs exist for H Reuse
interfaces
[BOF-DOC-02] TBO Docbase type M Reuse
definition documented
[BOF-DOC-03] Transaction environment M Reuse
expectations
documented
[BOF-DOC-04] Transaction behavior M Reuse
documented
[BOF-DOC-05] Component H Reuse
dependencies
documented
[BOF-DOC-06] Supported "features" H Reuse
documented
[BOF-DOC-07] Version H Reuse
(in)compatibilities
documented
[BOF-DOC-08] Customization hooks H Reuse
documented
[BOF-DOC-09] Java runtime H Reuse
requirements
documented
[BOF-DOC-10] Known issues H Reuse
documented
[BOF-DOC-11] License terms L Reuse
documented
[BOF-DOC-12] Support and contact info L Reuse
documented

Category Item Impact Significance Followed Justification

Y/N if ignored
Deployment
[BOF-DEPLOY-01] Jars, not classes H Standards/Quality
[BOF-DEPLOY-02] Implementation/interface H Standards/Quality
jars separate
[BOF-DEPLOY-03] Native code prohibited H Standards/Quality

Developer Program
Component Exchange 7/18
General Guidelines
Audience
This document is initially targeted at all internal Documentum engineering teams that
use BOF for the development of their respective products and applications. The
guidelines are also expected to be used by the external development community
including customers and partners.
How to be used
This document is intended to be used as a tool by developers to design and develop
BOF-based components to optimize the quality, reusability and extendibility of their code.
A decision may be made by the developer(s) of a given component to not follow specific
checklist items. In these cases, a justification should be documented such that the
trade-offs can be proactively evaluated.

Definitions and Overview of BOF Components

BOF Component Definitions and Overview
Service-Based Object (SBO)
Logical Definition
A Service-Based Object (SBO) is a standardized, client-independent way to provide
horizontal functionality.
An SBO is suitable when the behavior is not type related, or when an object related
behavior applies horizontally across types and is invoked explicitly by a particular client.
For more information, see SBO Design.
Physical Definition
An SBO component consists of:
• Implementation jar(s)
• Interface jar (separate).
• Interface Javadoc
• Descriptor (text or xml)

Type-based Object (TBO)

Logical Definition
A client-independent way to add/modify behavior associated with Docbase types.
For more information, see TBO Design.
Physical Definition
A TBO component consists of:
• Implementation jar(s)
• Interface jar (separate)
• Docbase type definition
• Interface Javadoc
• Descriptor (text or xml)

Developer Program
Component Exchange 8/18
BOF Component Guidelines
What Constitutes a Good BOF Component?
The following qualities contribute to the creation of a high-quality component.
• Friendly to their surrounding environment
• Designed with intelligent assistance for versioning
• Designed for extensibility
• Well documented
• Easily deployed
Environmental Friendliness
The following sections describe environmental factors that contribute to the success of a
BOF component.

[BOF-LOG] Logging
Components must use DfLogger. This is necessary in order to provide a consistent
logging environment. Use of “compatible” logging such as native log4j reduces the
extent of compliance (for example, it cannot participate in “client contexts”). Use of
incompatible logging environments (for example, Java 1.4 logging) would complicate the
deployment of components and impose a severe burden on clients.
The semantics that are attached to FATAL, ERROR, INFO, and WARN should be
consistent across products and development groups. “Low-level” code, unaware of its
context, should log only at DEBUG and WARN level. ERROR and INFO semantics
should remain under the control of the calling application, because an ERROR entry in a
log file will necessarily imply a significant (unrecoverable) problem to a customer, and as
a component developer you cannot tell whether or not the application is designed to
recover from an error condition reported by a lower layer. Similarly, what constitutes an
event worthy of logging cannot meaningfully be determined without knowledge of the
application context.
You should register any resource bundles with DfLogger in a static section.

[BOF-TRANSX] Transactions
Components must only use Session Manager-based transactions.
DFC has a working implementation of cross-Docbase commit behavior within the
Session Manager transaction primitives. You should exploit this rather than attempting to
code your own synchronized cross-Docbase commits.
Nested transactions are not supported, so do not initiate a transaction if there is already
another in the Session Manager. If a component requires transactional capabilities it
should always check its environment before attempting to create a new transaction.
If a component creates a transaction, it should commit or abort it within the method as a
default rule.
Put transaction commit or rollback behavior into a FINALLY clause of a method.
See the BOF documentation in the Documentum Foundation Classes (DFC)
Development Guide.

Developer Program
Component Exchange 9/18
[BOF-SESS] Session Manager
Components must always use Session Manager facilities.
Components must acquire and release raw sessions only as needed. They should not
acquire sessions and leave them open across method calls.
If a TBO is created and returned by an SBO, the SBO must take one of the following
actions:
The SBO returns the object ID rather than an object reference
The SBO puts TBOs under the control of the SBO’s Session Manager explicitly
BOF-VERS Versioning Support
IDfBusinessObject Methods
Components must implement the version-related methods of IDfBusinessObject
(isCompatible, supportsFeature) accurately.
Note: It is important to maintain this versioning.
It is an open issue whether the version revealed in getVersion should reflect changes to
base classes.
Support for “features” is an optional adjunct to version compatibility support (which is
mandatory). Features are a nice way of advertising functionality that avoids imposing
complicated version checking on the client. For example, a contract service could
support a “search” feature that is made available through a well-known interface. Just
checking support for that feature would enable a client to exploit the feature without
reference to explicit versions.
If the semantics or interface of a feature changes, then that constitutes a new feature,
and it should be named differently. Support for the original feature should be removed
when support for the new feature is added, unless the change is backward compatible.
More specifically, if the change is interface-compatible, but not semantically compatible,
then it is a destructive change, and without interface extensions can not be backward
compatible. On the other hand, it is not considered a change at all if you only change
some implementation without versioning the interface or breaking semantic guarantees.
Note: The feature namespace is designed to be local to SBOs – not global.

Developer Program
Component Exchange 10/18
Design
[BOF-SBO] SBO design
SBO components that are designed to be customized should use the strategy pattern
(customization) rather than the template pattern (extension). Although the template
pattern is accepted in Java, it is less suitable for SBOs.
For extended-service SBOs that were not initially designed to be customized, use the
decorator pattern to extend the service via composition with interface extensions.
You must use interfaces as method arguments, not classes, with the exception of String.
For example, use IdfList with a factory method rather than DfList.
Prefer DFC interfaces to equivalent Java lib interfaces or classes when available (e.g.
IDfCollection), because they are automatically available via the COM bridge.
Use IDfId to pass objects as arguments in interfaces. Do not use a subinterface of
IDfPersistentObject.
SBOs are conceptually similar to J2EE session beans.
SBO Interfaces and Exceptions
An SBO should be a well-defined service. The interface definition should be approached
with great care.
There are two primary goals for a well-designed interface:
• Abstraction
• Interface stability
To achieve the goal of abstraction, an SBO interface should expose in its interface only
those concepts that are appropriate to the service’s concerns and should avoid exposing
implementation choices that might undermine encapsulation.
The goal of interface stability is important because an SBO is more than just a Java
class. It is a component, and as such it has extra responsibilities that reflect its shared
usage role and its unique deployment circumstances, which leads to evolving
implementations. Proper attention to abstraction is already a key element in achieving
interface stability, but the component role of SBOs makes this goal critical and can justify
some pragmatic choices in interface design.
Some of the most crucial design concerns are the typing of method arguments and what
exceptions, checked and unchecked, are thrown.
Arguments to methods should be appropriately typed so that they do not unnecessarily
restrict the nature of the implementation. For example, a URL might be a better choice
than a filename if the nature of the resource is not intrinsic to the service. If at all
possible, arguments to methods should be interfaces rather than classes.
Checked exceptions arising from a particular service implementation that are not
conceptually relevant to the service definition should not be exposed in the interface.
Runtime exceptions that arise within the particular implementation should be wrapped in
a runtime exception specific to the service so that they are easily distinguished from
contract violations or runtime exceptions arising within caller code.
Note: Precondition violations constitute a proper use of unwrapped runtime exceptions,
because the failure relates explicitly to the interface contract. A pragmatic exception to
this rule might be to allow DfException to be thrown from service methods, because it is
both pervasive and familiar to our customers.

Developer Program
Component Exchange 11/18
Exceptions thrown by an implementation that are not relevant to the service’s concerns
should not be exposed to the service’s client. In the case of checked exceptions, these
should be caught and translated with exception chaining.
If the exception is due to a specific cause (i.e., one or more identifiable throw
statements), and these causes are relevant to the service’s concerns, then a specific
checked service exception should be thrown (with exception chaining). Before you do
this, be sure that this cause is not specific to the implementation choice but instead can
be expressed in terms of service concerns to avoid breaking encapsulation. If you
cannot express the exception in these terms then treat the cause as non-specific, as
described below.
If the exception cannot be tied to a specific cause, then the method should throw a
nonspecific checked service exception (with exception chaining). There should typically
be only one such exception class per service, and it will be the base class for the other
specific checked exceptions. An analogy in the standard Java libraries might be
java.sql.SQLException.
The practice of exception translation is a specific case of attention to abstraction. It is
also reasonable to map various error codes or statuses from implementation
technologies to normalized checked exceptions.
Note: It is still possible to throw checked exceptions that are not defined by this service.
For example, if a method argument is a URL then it is reasonable to include
MalformedURLException in the method signature. This is because the URL is part of the
interface contract and not just an implementation detail.
The following examples demonstrate recommended exception handling for projects
internal to Documentum.

Example: MyService.java
public interface MyService
{
/**
* Any runtime exceptions that can arise from precondition failures are documented in the Javadoc.
* No other runtime exceptions should be thrown (they should be wrapped). If the documented runtime
* exceptions are caught then their cause is exactly as described. Since these precondition failures
* should never occur in production code the client is never <b>required</b> to catch them. There
* should be no need for the client to catch other runtime exceptions that are outside their control.
* These represent failure of the service and should be encapsulated in a fault exception.
*
* The presence of a non-specific exception in the method prototype affords some degree of interface
* stability, but where exceptions are thrown for specific causes this is properly a part of the
* interface contract and so they should be listed in the throws clause. Any non-specific exceptions
* that are thrown should be explicitly documented in the Javadoc.
*
* @param s non-null string
* @param i non-negative integer
* @throws NullPointerException if the string argument is <code>null</code>
* @throws IllegalArgumentException if the integer argument is negative
* @throws MyServiceFaultException if the service implementation encounters a program error
* @throws SomeOtherMyServiceException if some other specific problem occurs in myMethod
*/
public void myMethod(String s, int i) throws MyNonSpecificServiceException,
SomeOtherMyServiceException;

/**
* This exception class is used as a base class for exception conditions that are
* aggregated rather than related to a specific identifiable documentable cause.

Developer Program
Component Exchange 12/18
 * In particular, it is often used when exception chaining is appropriate.
*
* Also note that this implementation is a restricted re-implementation of Java 1.4 chained
* exceptions that will work under both a 1.3 and 1.4 JRE. With 1.4,
* this code could be changed to exploit the 1.4 Throwable class directly with affecting clients.
*
* Exceptions that arise from lower-level exceptions must include the cause.
*/
public class MyNonSpecificServiceException extends Exception
{
Throwable cause = null;
public MyNonSpecificServiceException()
{
}
public MyNonSpecificServiceException(Throwable cause)
{
this.cause = cause;
}
public MyNonSpecificServiceException(String message)
{
super(message);
}
public MyNonSpecificServiceException(String message, Throwable cause)
{
super(message);
this.cause = cause;
}
public Throwable getCause()
{
return cause;
}
}

/**
* This service exception subclass wraps any internal runtime errors and projects such an
* occurrence as a service failure. This exception should not occur in production code,
* but the possibility exists so the service client should be given some opportunity to
* handle this condition at an appropriate level of abstraction. Note that the cause is
* explicitly wrapped.
*/
public class MyServiceFaultException extends RuntimeException
*/
{
public MyServiceFaultException (RuntimeException cause)
{
super("Internal error in MyService implementation - check cause", cause);
}
}

/**
* This service exception class is thrown in specific identifiable and documentable
* circumstances. As such, it becomes a part of the interface contract and appears
* explicitly in the throws clause.
*/
public class SomeOtherMyServiceException extends Exception
{
public SomeOtherMyServiceException()
{
}
}

}
Developer Program
Component Exchange 13/18
Example: MyServiceImpl.java
public class MyServiceImpl implements MyService
{
public void myMethod(String s, int i) throws MyNonSpecificServiceException,
SomeOtherMyServiceException
{
// Check preconditions and throw appropriate runtime exceptions to inform the client
// of any violations.
if (s == null)
throw new NullPointerException("String argument null");
if (i < 0)
throw new IllegalArgumentException("Integer argument must not be negative");

try
{
// Perform application logic
myPrivateMethod(s, i);

// Throw a specific exception when the cause is identifiable and documentable.

throw new SomeOtherMyServiceException();
}
catch (RuntimeException e)
{
// Any runtime exceptions encountered reflect bugs in the implementation.
// We should wrap these so that we can offer the condition to the client
// at an appropriatelevel of abstraction, without losing the causal details.
//
// Note that you should only replicate this catch clause in other implementation
// classes if the level of abstraction changes materially. It is fine to proprogate
// runtime exceptions within the same level of abstraction. Public entries to a service
// are unconditionally deemed to be a change in the level of abstraction.
throw new MyServiceFaultException (e);
}
}

/**
* In private methods, or in lower level classes, preconditions can be assumed because you are
* in complete control. In Java 1.4 you could use assertions liberally. In fact, you could choose
* to use asserts during the development cycle and then compile the source (using javac 1.4)
* specifying a target VM of 1.3.
*
* @param s
* @param i
*/
private void myPrivateMethod(String s, int i)
{
assert s != null;
assert i > 0;

// Some logic.
}
}

Developer Program
Component Exchange 14/18
[BOF-TBO] TBO design
Do not use capabilities (TBOs use public interfaces, called TEOs in the documentation),
because they will be obsolete in BOF 2 and have various limitations (for example,
session-based, hard to cache). Object-related behaviors that are horizontal across types
but not explicitly invoked by a particular client are not currently supported.
Best practice: Create an SBO that will expose a public interface as a façade, and tightly
couple the SBO to the TBO by invoking the functionality explicitly from the TBOs.
If you add new behavior to TBOs, it is a best practice to wrap the TBO in an SBO façade.
However, this is not necessary if you only override existing behavior. This policy is
intended to promote treating TBOs as implementation details for services rather than as
client-accessible objects. Your choice in this regard has consequences for the policy you
should adopt for exceptions. If you expose all the base class methods then it is at least
consistent (for new methods) and necessary (for overridden methods) to throw
DfException. If not, then it is best to define domain exceptions in a fashion similar to
SBOs.
Example: In a catalog management application, you could create an SBO interface for a
category management service as a façade. The internal implementation would use
private TBOs.
TBOs must implement IDfDynamicInheritance. If a TBO derives from an intermediate
class “between” itself and another base TBO, it is the intermediate class that must
implement IDfDynamicInheritance. Failure to do this could lead to different
implementations of the contract across versions.
A TBO interface must extend IDfBusinessObject but it is optional to extend
IDf<whatever> (eg. IDfSysObject). There are three suggestions:
1) Extend IDf<whatever> when many base interface methods are applicable.
2) Do not extend IDf<whatever> when base interface methods are infrequently
applicable (and a cast would be tolerable). This avoids polluting the custom
interface unnecessarily.
3) Redeclare specific base interface methods as needed on the private interface
when a few base interface methods are frequently applicable. This is relatively
safe as the base interface signatures are immune to capricious change.
The choice is one of convenience.
TBO extension is accomplished inherently via language extension.
TBOs are conceptually similar to J2EE entity beans.

[BOF-EXCEP] Exceptions
Do not log a DfException in SBO or TBO implementations, because it has already been
logged by DFC. However, it is acceptable to propagate DfExceptions. You might also
consider throwing a domain exception with the DfException as the cause.
How non-DFC exceptions are handled differs according to the following conditions.
For all SBOs, and TBO methods that are not legacy DFC methods and do not subclass
IDf<whatever>:
Use a different policy and substitute custom domain exceptions for DfException
subclasses (but not for actual DFC errors).

Developer Program
Component Exchange 15/18
 * Note: This recommendation for TBO methods that are additional to DFC methods only
holds if your TBO interfaces do not subclass IDf<whatever>. In all other cases, the TBO
methods should restrict themselves to subclassing DfException, described in the next
category.
For TBOs with new, non-DFC exceptions:
For TBOs with new methods that throw exceptions unrelated to DFC you should
subclass DfException if the exception is thrown from an overridden method.

[BOF-CONV] BOF Conventions/Standards

Naming Conventions
Although traditional usage within Documentum includes the use of an I- prefix for
interfaces (for example, IFoo) and also class and interface prefixes to suggest functional
grouping (for example, Df), these practices have a varying degree of suitability for both
TBOs and SBOs.

SBOs
SBOs are prime candidates for projection as web services. This is a material
consideration and one that will be more significant as time goes on. The traditional
Documentum conventions are not well-suited to web services. Other intuitive choices
can also prove to conflict with the goal of smooth integration with web service technology
(for example, a Service suffix). The following guidelines are suggested for SBOs:

Interface naming
The SBO interface is the primary name for the interface.
Do not use an I- prefix. This has the effect of polluting automatically generated WSDL
which should be as free as possible of language conventions. It also conflicts with
standard practice on .NET.
Do not use a -Service suffix. While this makes intuitive sense (for example,
InboxService) the effect in more than one web service infrastructure would be to create a
web service called InboxServiceService. This unfortunate real-world consideration
makes it quite difficult to come up with service names that are viable in both pure SBO
and web service situations. For example, just dropping –Service and using an
unadorned name (for example, Inbox) makes it difficult in many cases to distinguish a
service from a TBO.
Many intuitive service names turn out to be of the form <noun>Service, like InboxService.
In these cases we suggest you use an alternative of the form <noun><actor>, such as
InboxManager. This would produce a web service called InboxManagerService, which is
a bit contrived but a tolerable compromise.

TBOs
TBOs are far less likely to be exposed outside of their traditional context. Regardless of
the merits of the traditional naming conventions, they are familiar and pervasive. It is
reasonable to continue with traditional conventions. Prefixes other than I- for interfaces
are discouraged though, as they are completely unnecessary.

Developer Program
Component Exchange 16/18
[BOF-DOC] Documentation
In order to use a component intelligently, a client needs certain minimum documentation.
This could be provided as text or might even become a component descriptor. The
following documentation is required or helpful for reuse of BOF components.

[BOF-DOC-01] Javadocs exist for interfaces

[BOF-DOC-02] TBO Docbase type definition documented

[BOF-DOC-03] Transaction environment expectations documented

A component must define its transaction environment expectations explicitly. For
example:
• Does it require an existing Session Manager transaction?
• Will it participate within an existing Session Manager transaction?
• Is it non-transactional?

[BOF-DOC-04] Transaction behavior documented

A component should define its transaction behavior:
• Create
• Commit
• Rollback

[BOF-DOC-05] Component dependencies documented

Specify any versions of other components upon which this component depends. This
includes WDK component relationships.

[BOF-DOC-06] Supported "features" documented

Specify which “features” are supported and provide a description of them. (See the
section entitled “IdfBusinessObject Methods” for more information about features.)

[BOF-DOC-07] Version (in)compatibilities documented

Specify whether this version breaks compatibility with any previous versions.

[BOF-DOC-08] Customization hooks documented

Specify whether hooks have been made available for customization or extension of the
component For example, a contract service might allow for (or expect) a client to provide
company identification/address information independent of the service implementation.
This customization capability and the means for a client to exploit it must be documented.

[BOF-DOC-09] Java Runtime Requirements

If your business object uses a Java extension package (javax.*) that is not universally
deployed, you must state any dependencies your business object has on the Java
runtime environment. For example, use of javax.crypto is supported by Java 1.4 but
requires manual deployment of an extension jar for 1.3 environments. Similarly,
JavaMail is supported by J2EE 1.3 but requires manual deployment for J2SE

Developer Program
Component Exchange 17/18
environments. Although the practice is discouraged, if your business object only
supports Java 1.4, it must be documented.

[BOF-DOC-10] Known issues documented

Describe any known issues for this component.

[BOF-DOC-11] License terms documented

Specify the license under which is this component offered.

[BOF-DOC-12] (Optional) Support and contact info documented

Include support/developer contact information (include alternate phone numbers).
[BOF-DEPLOY] Deployment
The following requirements facilitate successful deployment of the component.

[BOF-DEPLOY-01] Jars, not classes

Components must be packaged in jars and not deployed as class files.
Private TBO interfaces should be included in the SBO façade jar, thereby limiting
visibility and improving consistency.

[BOF-DEPLOY-02] Implementation/interface jars separate

Interfaces must be deployed on the client side. Component writers must create separate
jars for interfaces and implementation. Component writers should “cluster” the interfaces
in jar files appropriately.

[BOF-DEPLOY-03] Native code prohibited

Do not use native code in business objects. This will cause enormous deployment
difficulties in BOF 2. For example, dynamic class loading will have problems, platform
independence will be lost, and app server restrictions will be violated.
Client Use of BOs
Clients of components must check versions/features of business objects that they use.

Key Documents/References
The following sections contain general requirements and best practices that apply to the
design of good components.
General
Overview of Development and Customization Options (Documentum Developer Site,
http://customernet.documentum.com/developer/Roadmap5/index.htm )
BOF-specific
Documentum Foundation Classes (DFC) Development Guide
Documentum Component Exchange (Documentum Developer Site,
http://customernet.documentum.com/developer/componentexchange.htm )
Effective Java Programming Language Guide, by Joshua Bloch, Addison-Wesley, 2001.

Developer Program
Component Exchange 18/18