Develop Reference

Why is it that many class methods and interfaces are not defined in the JSR documentation

I was looking to start a java project that would allow me to look at just the specification and implement the solution in java. I figured I would take a look JSR-173-Streaming-API-for-XML spec. and figured all class/Interface definitions along with class methods would be described in detail here. This spec does not define every class and method as I thought it would.
I found the specification at the following URL https://jcp.org/aboutJava/communityprocess/final/jsr173/index.html
in a .pdf file entitled jsr173_1.0.pdf.
The spec mention package javax.xml.stream so I figured all the API’s in that package would be explicitly defined in the specification.
For example, In the spec. I found the class javax.xml.stream.XMLOutputFactory but it only mentions one of it’s methods newInstance(), nothing about the other 14 methods the class has.
Other interfaces and Errors like FactoryConfigurationError and EventFilter from the javax.xml.stream package are not even mentioned.
So my question is, if not in the spec. where does it specify all the other class methods and interfaces for this API.
Thank You.

Why is it that many class methods and interfaces are not defined in the JSR documentation
First some facts.
Java 1.0 was released in 1996.
The JSR process was established in 1998 (source)
The first JSRs were producing public review drafts in around 2000.
By the time the JSR process was established, the core Java APIs were already mature. They didn't need (or weren't deemed to need) significant revision, and so a JSR was not warranted.
People don't form committees and so on if there is nothing to do. And people don't write and publish formal specification documents if they are objectively not needed ...
Secondly, some of the significant Java changes that were happening in the 1996 to 2000 time frame (e.g. in Swing, Collections) were being driven internally within Sun. You would need to ask the people involved what the real reasons were, but I suspect it was a combination of the following:
JSRs and other processes for producing specifications are done by achieving a consensus. This is an iterative process. The more people and organizations involved, the longer it takes. In some cases, it would have just taken too long.
There were probably people in Sun Microsystems at the time who didn't want too much involvement of non-Sun people in the design process for some of the APIs. For whatever reasons.
Finally, there are (probably) examples of more recent APIs or API changes where no JSR was involved. In some cases, the changes could have been the result of a JEP. In others, they could be a result of some internal Sun or Oracle decision to implement a feature or change without any (formal) external input. They had the right to do that kind of thing (and possibly still do).
So my question is, if not in the spec. where does it specify all the other class methods and interfaces for this API.
In that case, the specifications are the published (e.g. Java SE) javadocs. And if the javadocs don't specify some aspect, then the published (OpenJDK or other reference implementation) source code determines what actually happens or illustrates what should happen. You can download and read it.
(Note that API behavior that is not specified in (at least) the javadocs may be subject to change. Historically, the Java team has been careful avoid changes that will break applications implemented against older (public!) APIs. However there have recently been exceptions to that; e.g. the deprecation and removal of Applet support.)

Why separate the API definition and implementation JARs

For jstl tags, an API javax.servlet.jsp.jstl-api-1.2.1.jar & implementation javax.servlet.jsp.jstl-1.2.1.jar are provided.
For servlets, an API in servlet-api.jar & implementation jar from tomcat or GlassFish are provided.
For collections, API like java.util.List & corresponding implementations like java.util.ArrayList & java.util.LinkedList are provided.
IDE Netbeans is another example.
Implementation jar includes both the API(mostly interfaces) and its implementation, What are the advantages in providing a solution with an API JAR and their corresponding implementations(a separate JAR), for programmers/developers to use?
For developing enterprise applications using java, Is providing an API the standard approach for stable contract between developers?

I have advocated separating the API from its implementation in my Practical API Design book. At that time I valued the simple library as well as modular library approaches. We used them both successfully when designing NetBeans Platform APIs. I usually felt uneasy when it came to vendor library style - a common approach used in Java EE world.
Later I realized the optimal solution depends on the desired degree of proximity (see my detailed explanation). In short, it depends how closely the API author is related to the one who implements the API. Is it the same person? Is it a group that sit down and agreed on a specification? Are they different, but we expect way more users of the library than those who implement it? Or do we expect almost every user to implement (something in) the library? The answer to this question then leads to:
None to many
One to many
Few to many
Many to many
Proximity classification. Each of them can be handy in some situations. However, my all time favorite is many to many approach with full featured modular library design.

1) If you put the API in a different jar, then you can let it be used by clients that can't access the implementation. For example:
You can exclude the implementation from the compile-time classpath of clients, to ensure that clients of the API don't require any particular implementation.
You can exclude the implementation from the run-time classpath of API clients (either via ClassLoaders like servlets do or separate JVMs), so that clients can't depend on any particular implementation, and so that they can use libraries that would conflict with the ones that the implementation uses.
2) Not really individual developers, but it's common to use a strategy like that to avoid conflicts and unwanted dependencies between different development teams.

This is because only the API is standardised, and multiple implementations are possible, and the API is an incomplete specification. In the case of servlets, in addition to the servlets API, which your Web App uses, there is the web application server (Tomcat or Glassfish). The application server is a large program, with many other features and APIs. For a Web Application, your servlets are not "the program"; the application server is. It is not that your servlets delegate to the server, the server delegates to your code (in a WAR).

In programming using an implementation, you might need the API specification (interfaces, abstract classes etc) too.
Interface obj = new ClassImpletingInterface();
which could also be done as
ClassImpletingInterface obj = new ClassImpletingInterface();
If your program used only the latter, you might get away having just the implementation jar that didn't include the API package. As far as possible, one should use the former for better maintainability etc. Now the question of why can't the API package just be bundled into the implementation jar - one API one jar. Might sound simple, but may not be desirable. You might prefer to use the javax.servelet.jsp.jstl-api package obtained from the authentic source; not bundled in com.newbie.servlet-0.0.1.jar. There can be legal aspects that prevent such bundling. Further, an implementation not necessarily provide functionality for the complete specification. Your imports for an API could come from two different implementations as different parts, and they could be for different release levels of the specification. In that case, perhaps rare, each bundling a different release level of API may cause trouble because jar search within a directory is not completely defined. So, bundling of API and implementation into separate jars is cleaner.

Is there jave ee contract implementation?

Like on jdbc java provide an interfaces, I see the interfaces like a contract for implementers (Drivers from multiple vendor) to implement those interfaces with respect to their documented functionality from java.
But on java ee, and based on this answer :
https://stackoverflow.com/posts/7571260/revisions
It's the same case on jave ee, the application servers are vendors and they implement jave ee abstract API, but on jdbc (And I mentioned it just as an example) the interfaces on java.sql package define the contract, but on jave ee(for example HttpServlet class) where is the interface the defines the general rules from java to this class that application server have to implement?
or is there any external agreements among application servers to implement the functionality of java ee classes?
Or java ee doc (like on
https://docs.oracle.com/javaee/7/api/
)
is adopted as an agreement?
Some people will see my question is useless, but I want to know the root of any stuff I want to learn, and my mind is used to answer small deal questions.

There are test suites that the vendor implementations are tested against, which obviously need to pass. The specifications also need to be obeyed to be a valid Java EE implementation. The Javadoc API is not the spec, but rather a side effect of it.

Platform-Independent Java <-> C# Interoperability

We want to use existing C# sources within our Java project. So far, this would not be a great problem since using e.g. Java Native Interface (JNI) is quite straight forward.
The problem is that the software shall also run on non-windows OS. So, we can compile the C# sources with Mono in order to make them executable on e.g. Linux. But how about the integration within Java? JNI or any COM-based solutions for C# <-> Java interoperability are OS-dependent and only work e.g. on Windows.
One possible solution would be the implementation of webservices. Has anybody another idea of how to solve this problem? I would be very thankful for alternative suggestions!
Thanks very much!
Regards

This is maybe not an "answer" as such, more a bit of discussion of how I viewed a similar (I think) situation.
I had a major investment in a C#/.Net-based client-server style system. So when I decided that I also wanted to support an Android "client" app I looked into various options. To me the most important factor was to maintain my C# classes as the defining classes for the object interchange between the existing system and the to-be-written Java Android app.
What I eventually settled on, and tweaked to my liking, was a system where Google Protocol Buffers is the interchange media. (If you're not familiar with them they are a sort of JSON-like interchange format.)
https://developers.google.com/protocol-buffers/
At the .Net end I use ProtoBuf-Net, written by Marc Gravell (he works here at SO, I believe). It includes the ability to take .Net objects and generate .proto files, the defining file for Protocol Buffers.
https://code.google.com/p/protobuf-net/
At the Android end I use ProtoStuff, written by David Yu. There is a part of his code that takes a .proto file and generates the corresponding Java classes.
https://code.google.com/p/protostuff/
One problem I encountered was that this didn't work well for my .Net classes that are derived classes, which was most of them. I created a workaround that is described in my comment to the answer here:
How to get protobuf-net to flatten and unflatten inherited classes in .Net?
This is now working to my satisfaction.
Note that I haven't talked at all about how the Android app connects to the Windows-based system and how the communications is performed. That was secondary for me - my primary consideration was making the C# class definitions the definitive definitions and having Java classes created from them automatically, and then the object-to-object interchange. (In the event I'm using a home-made TCP/IP communications link, but the actual communications could be anything, probably also web services.)
Hope this helps.

So I did a lot of research on this topic and want to share my findings with you:
One (from a technical point very attractive) option is to use commercial bridges between Java and .Net. For sure, the most popular products are JNBridge and Javonet. Both products seem to be quite easy-to-use, have good support and seem to be very sophisticated. Especially JNBridge already supports bridging between Java and Mono too, which allows the portation to also non-Windows OS, which is one of our main requirements as stated above. Javonet also wants to integrate Mono and is going to release this feature soon. However, both solutions are commercial and one needs to weigh their features against the respective costs. Nevertheless, from a pure technical point of view, they look great and also state to enable very fast communication between Java and .Net (faster than with web services).
Another option is to connect Java and .NET via COM. Since COM is generelly defined platform-independently, this could work on multiple OS. There are lots of open source projects that could be used for such an implementation, such as EZJCOM, J-Interop, JACOB or JCOM. The main restriction (expecially for our project) is that Mono only supports COM-interoperability under Windows (yet). So, this is not really an option for us. But if you want to create Java-.NET interoperability on Windows only, this is a good way.
The straighforward way of integrating Java and C# is to use Java Native Interface (JNI). You can also find manifold implementations that make JNI more easy to use, the most popular one is probably jni4net which seems to be a very active and frequently used project. But there are also others with specific pros and cons, such as Caffeine, Espresso or csjni. Finally, JNI is not 100% platform independet. It is applicable on different platforms, but you have to generate platform-specific code which makes it clearly less usable for our purposes. If you limit your application to Windows, jni4net seems to be a very good choice.
The third option could be to run both the Java and the .Net part within a Common Language Runtime. Ikvm.net is one possible and very popular solution therefore (as mentioned above by Samuel Audet). The drawback of this option is the loss of features and efficiency of the JDK.
The last and surely most generic alternative is to set up webservices between the Java and the .Net world. For this solution, one needs to find appropriate ways for serializing/deserializing objects from/to Java and .Net. There are manifold possible solutions for that available. RenniePet mentioned a sophisticated solution based on Protocol Buffers. Others exist as well such as http://java-cs-bridge.sourceforge.net/. This option might have a potential drawback when considering communication runtime, but may be the way to go for us.
Hope this may help anyone in the future that is confronted with the same problem.

Why does Java have a central API documentation, but not C++?

Question pretty much explains it all. I've been wondering why Java has nice, organized and centralized API documentation, but C++ library definitions seem to be scattered across the internet?
Is it because Sun put some effort behind making Java API documentation easy and accessible? Thanks in advance.

What you call "nice, organized/centralized, API" for Java is probably the documentation of Oracles's official implementation. C++ implementations also have their own documentation, for instance, GNU's implementation is well documented in http://www.gnu.org/s/libc/manual/ (the C part), and in http://gcc.gnu.org/onlinedocs/libstdc++/ (the C++ part; see section "API and Source Documentation"). You will also be able to find in MSDN Library the full documentation for Microsoft's C++ implementation.
You probably find Java API more concise and well documented because there is only one serious implementation of it (Oracle's original implementation), making its documentation the very resource for the language itself.
On the other hand, C++ is a standard, implemented by a wide variety of vendors, and many documentation resources are not even based on any specific implementation, but in the standard itself. In the end, different C++ resources on the Internet tend to outstand others in some areas. For instance, cplusplus.com concentrate good documentation about <iostream>, <string> and beginners topics, while the documentation of SGI's implementation of STL (http://www.sgi.com/tech/stl/) became the reference resource for STL, probably because of its completeness and very good organization.

C++ has a language specification, and a set of standard libraries.
Java also has a language specification, and also has set of standard libraries.
I don't really see any fundamental difference between the C++ standards and the Java standards, except that Java also comes with a standard implementation (from Oracle, formerly Sun).
PS:
Admittedly, Java has a standard API for GUI's (Swing), and C++ doesn't. But do you really want to force a "standard" like Windows MFC, to the exclusion of alteratives like Qt?

Part of the difference comes from the fact that the C++ standard library is not as well defined as the Java equivalent. The C++ standard leaves a lot of room for implementations to behave slightly differently in certain cases, a luxury Java does not provide. So for Java, once you have one good, quality set of docs, you're done... everything you need to know is right there. But with C++, STLPort's documentation won't necessarily match Dinkumware's, for instance, and you end up with lots of scattered documentation.

One reason is that C++ is not tied to single vendor, so it's not centralized by default.
Another reason is that Java provided documenting comments as part of the language and Javadoc was available from the beginning as one of the standard JDK tools. This had an impact on availability of API docs. Generating API doc was always a natural stage in Java build model.
C++ is a different story. I have met following comment by Nathan Myers in GCC's basic_string.h implementation.
Documentation? What's that?
Only recently Doxygen established a de facto standard. For a long time documenting comment was like black magic. Each project relied on its own tools and even though some projects had very nice docs, those tools were not available for a general use. I remember people begging Trolltech to release Qt documenting tool but this never happened.
Accidentally stepped into this answer and realized it needs an update. In a meantime Qt Company has actually released QDoc. Moral: never say never.