Of course, TAPI still has a niche and is indeed embedded into many PC
modems, but its track record against its original goals is, shall we say,
modest. Some would say that it never saw the Internet coming. Of course,
technology development is almost Darwinian in the way it casts off also-rans.
VRML promised us the world and is much cooler than HTML; Microsoft’s Blackbird
would give us our information superhighway; JSDT would revolutionize application
collaboration; Network PCs, BeOS, BetaMax…
With the Java Community Process starting approximately 150 Java API
definitions now, it shouldn’t be surprising that not all of these will succeed.
InfoBus 2.0, for instance, was withdrawn. Of course, success can be measured
in different ways, and for some APIs even narrow adoption is appropriate.
That said, some are bound to fail when judged against their original goals.
Obviously JDBC and EJB are resounding successes, but what of JTAPI or JavaSpaces
or Java Speech API? This article looks at what makes a good API, what pitfalls
should be avoided, and who the winners and losers are.
Here’s a sampling of Java APIs that have suffered from less than overwhelming
adoption or are fraught with potential problems:
The Java Speech API targeted the same market as Microsoft Windows’ SAPI.
It basically offers capabilities for generating speech and performing speech-to-text.
While the market has never been huge despite Corel’s inclusion of speech
recognition in its Office Suite, there seemed to be some potential for a
JSAPI. Unfortunately, the number of implementations is somewhere around two.
• Small market niche: Despite the hopes of speech recognition
companies, this market is still small and specialized, with some inroads
into automated directory assistance services.
• No published API classes: Indeed the API is published
not as a set of interfaces and classes that implementors code against, but
as a document that must be implemented. This makes implementation more difficult,
leads to a high likelihood of typographical errors, makes it hard to develop
to the specification without a working implementation, and makes it very
hard to plug two vendor implementations into one system.
• Implementation isn’t decoupled from specification: Part
of the reason the API classes and interfaces are not published as code is
that the specification embeds the implementation in its definition. That
is, there’s no concept of interfaces that a vendor writes to and plugs into
an application using some factory method.
At the time of writing, the Preferences API (JSR #10) has been accepted
as part of J2SE 1.4. Its intent to provide a better registry-like replacement
for properties is long overdue and especially topical as the era of distributed
Java applications through mobile devices and Web services gains a new life.
That said, the Preferences API currently contains one fatal flaw: it
ties the persistence of part of an application’s state to a JVM. The Preferences
class delegates its calls to a subclass of the AbstractPreferences class,
which defines some Service Provider Interface (SPI) functions for completing
the actual management of data between the application and the Preferences
Like AWT, the determination of which SPI will be instantiated behind
the Preferences class is left up to the JVM implementation (a Java Property:
java.util.prefs.Preferences-Factory is suggested, but not mandated). This means that an application
has no way of plugging in an appropriate Preferences implementation – a networked
implementation for an applet and a local registry for an application. Needless
to say, it can’t plug two implementations into the same application.
Most troubling, since the Preferences backing store is tied to the JVM
implementation, you’ll lose all your Preferences if you change JVMs. Sure,
there’s support for exporting and importing Preferences, but this would require
users to manually migrate Preference information when they want to change
their JVM vendor. Depending on your system “path,” an application that can
also run as an applet may not be able to share preferences between run types.
It’s one thing for the AWT to tightly tie the implementation to a JVM – GUIs
are a transient aspect of an application after all – it’s quite another to
bind a persistence implementation to a JVM. On servers, in particular, it’s
not unusual to have several JVMs resident with different performance characteristics.
JTAPI started development in 1996 as a uniform way for applications
to access telephony services, hard on the heels of TSAPI and TAPI in the
“C” world. Since that time it has been through several revisions and, at
the time of writing, the current release is 1.3. Unfortunately, even after
all this time, the number of available JTAPI implementations can probably
be counted on one hand. Some are only test frameworks that offer no real
telephony access and, among the one or two released by reputable telephony
companies, it’s not unusual for them to “modify” the standard.
Why didn’t it take off? Well, there are a number of reasons.
• Complex API
JTAPI has to be one of the most complex APIs around, consisting
of 19 packages with over 250 interfaces to implement. Implementing and maintaining
all, or even part, of this is a major undertaking, which can only be justified
by significant developer demand. This becomes a vicious circle: no applications
mean no incentive to invest in JTAPI implementations, and with few implementations
there’s little incentive to build applications.
• Optional Hell
JTAPI allows most packages to be optional, meaning a vendor
doesn’t have to implement them. On top of this, even within interfaces, many
methods are also optional, permitted to raise the “MethodNotSupported” exception.
While an obvious side-effect of trying to map a unified API to a complex
and nonstandard industry feature set, this causes two problems. For JTAPI
implementors, we must now try to predict our client requirements and trade
that off against development complexity in order to determine which features
to support. We must also implement a whole “Capabilities” framework to expose
our feature set. For application developers, it provides extra uncertainty
since it’s not guaranteed that we’ll be able to plug in multiple vendors
to support our application.
The whole promise of JTAPI was decoupling applications from telephony
providers, but in reality all it does is provide a common development paradigm
for building Java telephony applications, since finding two JTAPI vendors
with a set of intersecting features that match an application’s requirements
is rather hard (actually, finding two JTAPI implementations of any kind is
no easy feat).
• Shifting Sand
Successful APIs offer gradual improvements. Unfortunately, JTAPI 1.3 saw listeners replace observers and a wholesale change
in the way media was controlled. Even worse, while listeners were added to
the core JTAPI package, subpackages such as “call control” didn’t have listeners
added yet. So, to receive “call control” and “core” call events, you either
have to add both an observer and a listener to the call or just add an old
style, deprecated observer.
• Broken Standard
As was mentioned in the previous point, JTAPI changed
the way media was controlled in 1.3. Unfortunately, the 1.3 API was rushed
out before it was properly completed, as can be seen by the simple fact that
the “media” API can’t be implemented.
To control media, an application should instantiate a “MediaService”
implementation, which by necessity must be tied into the JTAPI implementor’s
private code. But there’s no “Factory” capability defined in the API, only
a “Basic-MediaService” class for subclassing. But BasicMediaService extends “NullMediaService”
and so can’t be tied easily to a real implementation. Real implementations
are forced to replace the JTAPI API classes or provide proprietary solutions.
Thankfully this is being fixed in JTAPI 1.4.
• Lack of CTI Market
The Computer Telephony Integration (CTI) market, like
many high-tech startups, is always “just about to explode.” Maybe the arrival
of the Internet has taken away the original vision of CTI. Nevertheless,
while this is not a problem as we can attach to JTAPI directly, it does highlight
how a complex API combined with a nonexistent market is a death blow.
• No Vendor Support
JDBC offers a vendor-neutral view of relational data,
and RDBMS vendors (and third parties) have endorsed it heartily. After all,
what good is a database if applications can’t access it? In addition, database
vendors tend to market their products based on performance, price, and reliability.
The telephony market is very different. Telephony vendors market on
feature sets (“Vendor X may support ‘Park’, but we support ‘Park’ and ‘Camp-on’”),
regardless of how few users know how to press the right combination of “*”,
“#”, and numbers to use the features. A telephony system without application
access is, well, still a telephony system. Considering the complexity of
JTAPI, there’s no compelling reason for most vendors to implement it.
• No Reference Implementation
JTAPI has never provided a reference implementation against,
for example, TAPI in win32. This leads to legions of frustrated developers
flooding the JTAPI mailing list with questions about where they can get an
implementation to run their code against. Eventually they go away and the
potential vendors have no set of JTAPI applications to justify development
of a JTAPI implementation. Chicken and egg. Even though the Java Community
Process now requires reference implementations for Java Specification Requests,
this requirement was unfortunately waived for JTAPI 1.4.
• Fragmented Market
Finally, we should note that JTAPI is not even the only
telephony API being developed under the Java Community Process. There’s also
a Parlay-based “service provider application” API and Jain Jcc and JCAT.
Despite this litany of problems, there may be some hope on the horizon.
Recently there has been a push to rationalize the Jcc, Parlay, and JTAPI
APIs so they’re not isolated islands but build off each other. More important,
JCC/JCAT is targeting the ongoing convergence of voice-into-network services
and this is a space in which Java is attractive to implementers, much as
Java has become firmly entrenched in the application server market. JCC/JCAT
not only targets a real and growing market, it’s also cut down significantly
on the size of the API that vendors must implement. And JCC has been released
with a reference implementation, so maybe the lessons are being learned.
These three case studies illustrate some of the problems that can doom
an API to marginal use. It’s important to understand these if we don’t want
to repeat past mistakes. Even in an internal development effort, a company
will want to ensure that any reusable framework being developed for internal
usage will be used, or else why put money into developing it?
1. Make sure the framework has a market: VRML is a cool
technology, but no one could figure out how it could provide value to users.
2. Make sure the API has vendors: If you’re developing
an API to interact with telephony systems, the vendors of those systems are
not going to write implementations to your API unless they want your users
and are willing to conform to a standard. After all, in some markets, vendors
sell based on their differences from other vendors, not their compatibility.
3. Entrenched opposition: Systems change slowly and you
must show a significant benefit over existing systems in order to convince
developers to risk moving to a new API. Databases are a case in point. Corporations
have a large investment in relational databases and JDBC is mature, so any
object-oriented API that connects to an object database is fighting an uphill
4. Complexity: There’s always a tradeoff between power
and simplicity. Try to enable developers and service provider implementors
with a minimal set of core features.
Winners and Losers
Let’s cut to the chase. Which APIs have failed to meet expectations
and why? Note that Table 1 is a subjective list and I’m sure I’ll take abuse
for it. Furthermore, while some of these APIs have failed for technical reasons,
often the source of failure has as much or more to do with shifts in the
This list is by no means exhaustive, but it does give you some idea
of which APIs have taken the right steps. The success of Java on the server
has also tilted the balance in favor of server-side APIs such as JSP, EJBs,
and JNDI. Some APIs, such as Swing, generate such a vigorous debate that
they can only be described as flawed successes.
The Case for Some Guidance
One of the most striking things about the Java APIs, once you’ve dug
into the details, is the lack of consistency in their design decisions. Since
each API has been developed by its own team, with only limited overall guidance,
maybe this shouldn’t be surprising. Some teams choose to support pluggable
implementations using an explicit Factory pattern (e.g., JTAPI), others hide
the factory behind an obscure system property (e.g., AWT peers), while yet
others use a URL lookup of registered providers (e.g., JDBC).
This means that developers must learn the usage paradigm of each API
separately and usually can’t take that usage pattern knowledge with them
when they move to a new API. Now maybe this is justified – I do expect to
have more control over what database driver to use than how the AWT renders
my widgets – but nevertheless a little bit more consistency wouldn’t hurt.
While the JCP does have a steering committee, it seems limited in its
ability to approve APIs and resolve API overlaps. Java would benefit from
a steering committee that provided an overall pattern framework for the APIs.
For instance, they may define the preferred patterns for plugging vendor
implementations into an API using a Factory pattern.
Under the Java Community Process 2, the process has been updated to
correct some flaws in the original. In particular, JCP 2.0 requires that
both a reference implementation and a compatibility toolkit be produced for
the API. The requirement for a reference implementation has been successfully
used before by the OMG in its CORBA standards and helps to spur on developers;
this in turn makes vendors more interested in implementing the API. A reference
implementation also ensures that an API is feasible. Similarly, a compatibility
toolkit helps to keep API implementations from fragmenting. Unfortunately,
the JCP 2.0 came along too late for JSAPI and JTAPI.
Even with these improvements, there are still some areas where the JCP
could be improved. The JCP works on a consensual model, as opposed to the
OMG adversarial model of Request for Comments and Request for Proposals.
While this can speed up API development, in the real world it can also stifle
options. Usually the specification lead comes from the group that first proposed
the API, and it’s not surprising that they may come into the process with
some preconceived notions of an appropriate architecture.
Better and more consistent APIs might evolve if different groups could
propose to the JCP Executive Committee (or better yet, a JCP Community Forum)
alternative API architectures and patterns and have the API “direction” come
under some competition. Once this high-level phase is resolved, the different
sides could be brought together into a consensual group and proceed as they
The Java Community Process has learned some valuable lessons since the
JCP 1.0, but still it could benefit from better cohesion if:
• Platform design pattern standards were defined.
• More competition for initial API “architectures” was supported.
• A dependency map of technologies was clearly laid out (I depend on
EJBs, which themselves use JNDI, so I can use JNDI without inflicting extra
dependencies on my applications).
• All JSRs required a reference implementation.
• Optional packages and methods made up a minority of the API.
• APIs were accompanied by usable classes the developers can import into
their development environment and code against.
Of course, this whole discussion also applies to the creation of APIs
by other parties, internal to an organization or not. Using RFPs in the development
of a proprietary API might not make as much sense, however. And getting open
source projects organized enough to adopt RFPs on a wide scale may be a bit
Despite my criticisms, I should point out that the standard Java APIs,
like many proprietary APIs and APIs in other languages, are the result of
a lot of hard work by bright people. When an API is flawed, as opposed to
just not adopted widely, it’s often due to the lack of an overall guiding
framework that ensures that the API works well with other APIs and fits into
a coherent usage paradigm. For a successful API, here are some simple rules:
1. Find an industry niche with a high value for developers, high enough
to offset the extra cost of learning a new API. An example is JDBC. Of course,
as the Java “platform” matures, these niches tend to get narrower and narrower
until a new technology bursts on the scene (e.g., XML, SOAP).
2. Hide complexity from the user of the API, but not so much complexity
that the API is hard to implement. The harder it is for vendors to implement,
the fewer implementations there will be. This prevents developers from using
it, which in turn discourages vendors from implementing it. Both JTAPI and
JSAPI (speech) have suffered from a dearth of implementations, partly due
to the complexity of the API implementation. On the other hand, HTML and
HTTP are examples of standards that are wildly successful because they were
just complex enough to be useful.
3. Ensure that the vendors are there. While telephony vendors were actively
involved in developing JTAPI, there wasn’t a lot of incentive for them to
actually build implementation. Traditional PBXes and Switches have been marketed
on their differentiating features instead of performance, quality, or price,
which doesn’t lead telephony companies to want to present an API that hides
4. When choosing between sticking to a widely adopted pattern or implementing
a “better” but unusual pattern, stick to the pack. There are various pluggability
patterns employed by APIs to hook applications to API implementations, such
as a Factory pattern or registry, broker, or system property. Unfortunately,
there are too many of them.
5. When an API manages the persistent aspects of an application, ensure
that it’s not tightly tied to the JVM. It’s one thing for AWT to be tightly
bound to the JVM, quite another for the Preferences API to be bound to the JVM.
While I’ve concentrated on the well-known Java Community Process APIs
(familiar to most developers), the same lessons apply to internal proprietary
APIs as well as non-Java APIs. The pitfalls and lessons discussed here apply
just as much to internal development efforts as to public ones. After all,
even inside a company a successful API still has customers who must be kept
The current rush to XML standards – which are not programming APIs but
data formats – provides an eerie parallel to this discussion. In fact, in
reviewing the debris being left on the Java API highway, it becomes obvious
that while there are technical errors, the most common reason an API dies
or doesn’t reach its anticipated potential is that the technology market
shifts, leaving InfoBus and JAF wondering what happened to visual JavaBean
assemblers even as the market moved toward server-side Java.
There’s nothing about Java, compared to other languages or platforms,
that has led to poorer APIs, and a lot has improved. Object-oriented code
enables easy pluggability, interfaces provide nice decoupling between the
API and the implementation, and packages are extremely useful name-space
separators. If I appear critical of Java APIs, it’s like the criticism you
may give to a beloved child. Since mistakes are always easier for armchair
critics to find afterwards, it should be noted again that most Java APIs
are well crafted and that the efforts of the API designers is and has been
diligent and thoughtful.
But there’s always room for improvement.
• JSAPI: http://java.sun.com/products/java-media/speech/
• Preferences API: http://java.sun.com/j2se/1.4/docs/guide/lang/preferences.html
• JTAPI: http://java.sun.com/products/jtapi/index.html
• InfoBus: http://java.sun.com/products/javabeans/infobus/
• JavaBeans Activation Framework: http://java.sun.com/products/javabeans/glasgow/jaf.html
• JSDT: http://java.sun.com/products/java-media/jsdt/index.html
• JINI: www.jini.org/
• JavaSpaces: http://java.sun.com/products/javaspaces/
• Open Service Gateway Specification: www.jcp.org/jsr/detail/8.jsp
• Orthogonal Persistence: www.jcp.org/jsr/detail/20.jsp
• JSP: http://java.sun.com/products/jsp/
• Servlets: http://java.sun.com/products/servlet/index.html
• EJB: http://java.sun.com/products/ejb/index.html
• XML: http://java.sun.com/xml and
InfoBus 2.0, JavaBeans Activation Framework
• While JavaBeans are a great way of providing a pattern
for IDEs to use to inspect arbitrary widgets, the InfoBus idea of hooking
these together through an asynchronous data bus never really caught on with
developers or tool vendors. It’s simply too easy to wire bean events to event
handlers that manipulate other beans directly through code. Similarly, the
JAF, while not technically flawed, envisioned a role for Java that has not
• Market for distributed media Java applets and applications
• Competes with RMI and CORBA as yet another distribution
Open Service Gateway Specification
• No pressing need
• Home networks are generally run by tech-savvy types who
prefer the mature facilities provided by a Linux box
• Object databases are a niche market
• Competes with Java data objects
• Small market
• No reference implementation
• No interfaces to build against
• No reference implementation
• Too complex
• No incentive for vendors
• Inconsistent and broken API
• Couples an application’s persistent state to a JVM implementation
• Yet another distribution framework
• Cool idea but no driving need
• Targeted a need for server-side page generation with
a clean language and server portability
• Popular on the server due to platform independence and
• Provides standard to unify server application framework
that was already evolving to meet the need
• Hot technology
• Pluggable architecture
• Bridge to corporate data that drives many applications
• Vendors have incentive to provide drivers since they
need applications to have access to their databa
• While there was some controversy when the Collections
Framework was being developed, especially for its refusal to reuse the popular
JGL, it has succeeded due to its simplicity and, most important, its inclusion
as a core Java package.
• Ties into a popular industry niche of naming and directory
services with a flexible and simple API. It doesn’t hurt that the wildly
popular EJB standard uses JNDI as its discovery mechanism.
Richard Deadman is a consultant in distributed Java systems with interests
in metainformation and dynamic business logic. He holds an MS in computer science.