directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Stephen McConnell" <>
Subject RE: Coding Standards: API, IMPL and reuse
Date Thu, 23 Sep 2004 18:08:56 GMT

> -----Original Message-----
> From: Noel J. Bergman []
> What is acceptable to expose in an API?  And where?  Java
> lacks a means to express it, but not all packages are intended 
> for public consumption.

Just a quick overview of the sort of things I consider as acceptable
content in an API:

  1. service interfaces
  2. exceptions
  3. other immutable datatypes

With respect to service interfaces - these should not expose aspects
related to object instantiation, deployment or implementation strategy.
Exceptions and other immutable datatypes exposed in an API should only
include those classes exposed by and documented under service

Furthermore, the quality of the interface can be impacted by the
references it contains to external APIs and Java classes. Reference to
external APIs should in general be handled with caution as this
represents exposure of your own API to an external development cycle.
Specifically - major version changes within an external API while
manageable at build time - are not necessarily under your control at
runtime. Lastly, reference to Java classes should not include
implementation classes.

Above and beyond the content of the api is the subject of identification
of the purpose of the api. In particular - is the api for a client, for
management, or some other aspect?  Identifying the role of the user will
often result in the identification of different apis (e.g. client api,
management api, plugin service provider (SPI), etc.).  Lastly,
separation of these different concerns under identifiable codebases
enables better integration within the java security framework. 

Cheers, Steve.

View raw message