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.
Related
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.)
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.
I'm a beginner in Java EE technologies. I wonder what the difference is between the jstl-api jar and the jstl-impl jar.
Why are the API and implementation separated? Does it mean there are other implementations available?
The API and implementation are separated, because Java EE works with a standardized specification.
The API is part of that specification, and contains a set of mostly interfaces to which everybody that participated in creating said specification agreed. In theory everyone can make an implementation that implements the published standardized API and behaves as described in the associated specification document. You are allowed to call your implementation "certified" when it passes the so-called TCK (Technical Compliance Kit).
It's a stated goal of this specification system to encourage competition, while at the same protected users form being locked-in to any specific implementation.
JSTL in particular is part of the JSP spec, which has been developed under JSR 245. If you would like to make your own implementation, you'd begin with reading the spec document.
Could you point me to any tutorials that explain how to write our own impl for jstl?
There are as far as I know no specific tutorials for creating your own implementation of whatever Java EE specification. It's in nearly all cases pretty much an expert job, and a job which is typically only carried out by a select few organizations or individuals. This kind of material doesn't really lend itself to tutorial-like write ups, although David Blevins (of TomEE fame) has given us the occasional glimpse in the work that is approximately involved with this.
jstl-api contains the interfaces that need to be implemented. The jstl-impl contains the standard or default implementation of those implementations. Why do you need both? because if you want the standard or default functionality you use the jstl-impl, but if you want to implement your own behaviour, you can override the methods of the interfaces in jstl-api. That's what a API means: Application Programming Interface. Best regards.
in a library i'm having problems with there is this class
com.sun.media.jmc.MediaProvider
which i want to have a look at.
i can't find a javadoc or anything for it, how do i find out its methods etc?
The classes of the package com.sun.* (and sun.*) are internal classes which backs the standard Java API. They are undocumented and subject to changes among versions and builds. You should in fact never make use of them in your Java code, else your code will break when you change the API implementation. Also see this SO topic.
In this case, the com.sun.media.jmc.MediaProvider is part of the Sun reference implementation of the JMF API (javadocs here). You are supposed to make use of the classes documented in the JMF API only. The (abstract) factories/builders will invisibly provide the Sun reference implemtations.
You should also consider Xuggler, which supports more codecs than JMF, is free and open-source, and is actively developed and supported (unlike JMF).
Question from a C-guy who has to work with some java code that is connected to my C-code via JNI.
I have to work on the build-system, and I'm trying to change that from a shell-script to a proper makefile. For the C-part that's easy, but the java side somehow involves xdoclet stuff.
I haven't yet found out what xdoclet is all about, and I want to understand it all.
I did my Google research, but I have no idea what that thing does. For me it seems like you only have a chance to understand the official documentation if you're already familiar with the problem and you have 10 years of java work under your belt.
Could you please - for dummies - explain what does xdoclet does?
Btw - also I've mentioned C. I'm into object oriented programming as well. There is no need to explain the basics of classes or inheritance (if required to understand xdoclet) to me.
Edit: It's been for IT things roughly a decade ago that I've asked this question. I still have no idea what xdoclet is, but the question got over a thousand views. I would like to see some java guy to chime in and finally clear things up.
The 10000 foot view of XDoclet is that it's a code generation engine. IMO, the interesting thing about XDoclet is how it does what it does, as opposed to what it does.
There is a tool called javadoc that takes annotation in source code comments and generates html documentation with it. This is the classic example of what javadoc was originally designed to produce. In an effort to support different output formats, the authors of javadoc made it plugable -- you can write "doclets" that plugin into the javadoc engine. This allows them to leverage the same source code parser, and emit different documentation output.
XDoclet is a clever hack that uses this engine to do code generation instead of documentation generation.
An example of usage would be: the developer manually writes a class that contains business logic, adds a few xdoclet annotations to the javadoc, and xdoclet generates additional code that provides transactional integrity.
EDIT:
As erickson notes, Java 5 added support for annotations as a language feature that can be processed directly by the compiler. As a result, the functionality that XDoclet used to provide can now be performed directly by the Annotation Processing Tool (apt) that ships with the JDK. Because of this XDoclet is now generally considered to be obsolete.