What exactly is a Specification?

java specifications requirements
Koray Tugay picture Koray Tugay · Dec 24, 2015 · Viewed 10.2k times · Source

I read or hear sentences such as:

The Java Persistence API (JPA) is a Java application programming interface specification...

or

JavaServer Faces (JSF) is a Java specification...

but I am not sure if I understand what a specification exactly is..

Lets say I create a new specification JMA, Java Math API, which is a Java Math Specification..

Is it enough that I define my specification as follows:

JMA must provide a method that adds two integers?

or, do I have to create a document something like:

JMA must provide the method: int jmaAdd(int x,int y)?

or, do I have to create the interfaces and distrubute the source code?

public interface JMA{
    int jmaAdd(int x,int y);
}

or do I have to compile the interfaces and publish it as jar?

Also, can a specification contain abstract classes or classes at all? Or must it consist only of interfaces?

What makes a specification, a specification?

Answer

Jörg W Mittag picture Jörg W Mittag · Dec 25, 2015

Is it enough that I define my specification as follows:

JMA must provide a method that adds two integers?

That's a specification.

It's not a very useful one, because it doesn't give many guarantees to the user of an implementation of that specification. If I wanted to write a program that adds two integers, I couldn't do it just from reading the specification.

It does give the implementor a lot of freedom, though. Generally, you want your specification to be precise in the points that matter to the user, but vague in the points that matter to the implementor. That way, the user gets the guarantees he needs to be able to write his programs, but it also gives the implementor the freedom to tailor his implementation to his particular niche.

For example, the Java Language Specification doesn't say anything about Garbage Collection. It only defines when objects are and aren't reachable, and it defines that you can create new objects. How the memory allocation works, how the garbage collector works, whether it is a reference-counting, tracing, or region-based collector, etc. all of those are left out, and thus different implementations for different niches can use different garbage collector implementations, and different implementations for the same niche can compete with each other.

or, do I have to create a document something like:

JMA must provide the method: int jmaAdd(int x,int y)?

That's also a specification. It is even less useful than the one above. It does define the name of the method, but it doesn't define what it does.

int jmaAdd(int x, int y) { return x - y; }

is a perfectly valid implementation of that specification, as is 

int jmaAdd(int x, int y) { return 0; }

Again, there are no guarantees for the user and too much leeway (or more precisely: leeway in the wrong areas) for the implementor.

or, do I have to create the interfaces and distrubute the source code?

public interface JMA{
    int jmaAdd(int x,int y);
}

I wouldn't necessarily call that a specification. That's code, and thus an implementation.

Note: of course, in Java, interfaces provide specification of behavior that classes then implement. But that's not what is meant by the term specification the way you used it in your question.

or do I have to compile the interfaces and publish it as jar?

Again, that's an implementation.

Also, can a specification contain abstract classes or classes at all? Or must it consist only of interfaces?

A specification doesn't contain anything. It's a piece of paper.

Typically, specifications are written in English. Well, actually, they are written in a specialized specification-writing language, which is often a highly stylized formal subset of English with specific semantics. For example, BCP14/RFC2119: Key words for use in RFCs to Indicate Requirement Levels defines the precise meaning of some common English words in relation to IETF standards documents. (Interestingly, it is also a specification, thus making it a specification for writing specifications.)

Formal Logic is also sometimes used, especially in Programming Language specifications to describe typing rules. And sometimes, even specialized Formal Specification Languages are used, like the Z Notation.

What makes a specification, a specification?

The simple and not very satisfying answer is that a specification is a specification if it is called a specification by people who care about specifications. (Or more generally: thought about as a specification.)

Different communities have different views on specifications. And different names for them.

For example, the original specification for the programming language was simply published in a scientific report. Then after a few rounds of improvements and new reports, they published the "Revised Report on the Algorithmic Language Scheme". And after that the "Revised Revised Report on the Algorithmic Language Scheme". With that began a kind of in-joke, and the current version of the language is defined in the "Revised Revised Revised Revised Revised Revised Revised Report on the Algorithmic Language Scheme", commonly written the "Revised7 Report on the Algorithmic Language Scheme" or just "R7RS".

None of those reports is called a "specification", yet every single one is a specification. Before Scheme, ALGOL also used the term "Report", as did several other languages.

Internet RFCs are also a good example. Technically, all an RFC is, is a "Request for Comments". Only very few of those RFCs are actually elevated to "Standards" status. Some are also "Best Current Practices". None of them are called "Specification", but many of them are treated that way. For example, HTTP is not a standard, but it is treated as both a standard and a specification, and significant portions of our new world economy are built on that.

If you want to get a feel for specifications, it's probably best if you just read some:

Related questions

Java's L number (long) specification

It appears that when you type in a number in Java, the compiler automatically reads it as an integer, which is why when you type in (long) 6000000000 (not in integer's range) it will complain that 6000000000 is not an integer. To …

Read More
Java: extending a class and implementing an interface that have the same method

Probably the following cannot be done (I am getting a compilation error: "The inherited method A.doSomthing(int) cannot hide the public abstract method in B"): public class A { int doSomthing(int x) { return x; } } public interface B { int doSomthing(…

Read More
Max name length of variable or method in Java

Is there a max length for class/method/variable names in Java? the JLS doesn't seem to mention that. I know very long names are problematic anyway from code readability and maintainability perspective, but just out of curiosity is there …

Read More