HomeDigital EditionSys-Con RadioSearch Java Cd
Advanced Java AWT Book Reviews/Excerpts Client Server Corba Editorials Embedded Java Enterprise Java IDE's Industry Watch Integration Interviews Java Applet Java & Databases Java & Web Services Java Fundamentals Java Native Interface Java Servlets Java Beans J2ME Libraries .NET Object Orientation Observations/IMHO Product Reviews Scalability & Performance Security Server Side Source Code Straight Talking Swing Threads Using Java with others Wireless XML

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.

Case Studies
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. Why?

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 backing store.

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.

Avoiding Pitfalls
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 battle

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 technology market.

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 do now.

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 optimistic.

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 this differentiation.

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.

Parting Shot
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 happy.

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 and www.jcp.org/jsr/detail/10.jsp

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 http://java.sun.com/xml/jaxp/index.html


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 materialized.

•    Market for distributed media Java applets and applications is small
•    Competes with RMI and CORBA as yet another distribution infrastructure

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

Orthogonal Persistence
•    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

JINI, JavaSpaces
•    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 vendor neutrality
•    Provides standard to unify server application framework that was already evolving to meet the need

XML Parser
•    Hot technology
•    Pluggable architecture

•    Bridge to corporate data that drives many applications
•    Vendor-neutral
•    Vendors have incentive to provide drivers since they need applications to have access to their databa

Collections Framework   
•    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.

Author Bio
Richard Deadman is a consultant in distributed Java systems with interests in metainformation and dynamic business logic. He holds an MS in computer science.

[email protected]

All Rights Reserved
Copyright ©  2004 SYS-CON Media, Inc.
  E-mail: [email protected]

Java and Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. SYS-CON Publications, Inc. is independent of Sun Microsystems, Inc.