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).
Related
The compiler display warnings if you use Sun's proprietary Java classes. I'm of the opinion that it's generally a bad idea to use these classes. I read this somewhere. However, aside from the warnings are there any fundamental reasons why you should not use them?
Because they are internal APIs: they are subject to change in a undocumented or unsupported way and they are bound to a specific JRE/JDK (Sun in your case), limiting portability of your programs.
Try to avoid uses of such APIs, always prefer a public documented and specified class.
The JDK 6 Documentation includes a link titled Note About sun.* Packages. This is a document from the Java 1.2 docs, so references to sun.* should be treated as if they said com.sun.*
The most important points from it are:
The classes that Sun includes with the
Java 2 SDK, Standard Edition, fall
into package groups java.*, javax.*,
org.* and sun.*. All but the sun.*
packages are a standard part of the
Java platform and will be supported
into the future. In general, packages
such as sun.*, that are outside of the
Java platform, can be different across
OS platforms (Solaris, Windows, Linux,
Macintosh, etc.) and can change at any
time without notice with SDK versions
(1.2, 1.2.1, 1.2.3, etc). Programs
that contain direct calls to the sun.*
packages are not 100% Pure Java.
and
Each company that implements the Java
platform will do so in their own
private way. The classes in sun.* are
present in the SDK to support the Sun
implementation of the Java platform:
the sun.* classes are what make the
Java platform classes work "under the
covers" for the Sun Java 2 SDK. These
classes will not in general be present
on another vendor's Java platform. If
your Java program asks for a class
"sun.package.Foo" by name, it may fail
with ClassNotFoundError, and you will
have lost a major advantage of
developing in Java.
Try running your code with a non-Sun JVM and see what happens...
(Your code will fail with a ClassNotFound exception)
Yes, because nobody guarantees that these classes or API will be the same with the next Java release and I bet it's not guaranteed that those classes are available in Java versions from other vendors.
So you couple your code to special Java version and loose at least portability.
Sun's proprietary Java classes are part of their Java implementation not part of the Java API their use is undocumented and unsupported. Since they are internal they can be changed at any time for any reason that the team working the Sun JVM decides.
Also Sun's Java implementation is not the only one out there! Your code would not be able portable to JVMs from other vendors like Oracle/BEA and IBM.
Here is Oracle's answer: Why Developers Should Not Write Programs That Call 'sun' Packages
I recently had a case that showed a real-world problem you can hit when you use these classes: we had code that would not compile because a method it was using on a sun.* class simply did not exist in OpenJDK on Ubuntu. So I guess when using these classes you can no longer say things like 'this works with Java 5', because it will only work on a certain Java implementation.
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.
I am using the AWTUtilities class in my application to create custom window shapes. As far as I know, there is no other way to do it. It is a requirement.
The javadoc generation gives me this error:
warning: com.sun.awt.AWTUtilities is Sun proprietary API and may be removed in a future release
What exactly does this mean? I can use it, but it may stop working with any release? Why put it in, then? More importantly, and the real question here, if Sun takes it out, will they likely replace it with another way to do the same thing? Is that what the warning is for?
I suppose I could just check for the presence of the AWTUtilities class before calling the code. But that's just obnoxious if I don't need to do it.
Does anyone have any experience with similar classes? Were they eventually accepted into the API and the warning removed or replaced with another method of doing the same thing? Do I need to be concerned about this?
FYI, I have read this:
How to distribute AWTUtilities
The Oracle documentation states:
Note: the com.sun.awt.AWTUtilities class is not part of an officially supported API and appears as an implementation detail. The API is only meant for limited use outside of the core platform. It may change drastically between update releases, and it may even be removed or be moved in some other packages or classes. The class should be used via Java Reflection. Supported and public API will appear in the next major JDK release.
JDK 7 has been a long time coming so it could be awhile. Whether you should use it is a risk management question that only your company can answer. If we are talking about an internal application where the deployed JRE can be guaranteed then you are not going to have a problem because you can guarantee a compatible JRE. If we are talking about deploying to external customers then you need to have a support plan if this provisional API ever changes.
A stable way to do this would be to create a Shell in SWT as per this snippet and then use the SWT_AWT bridge to get a Frame to use in your application:
java.awt.Frame frame = SWT_AWT.new_Frame(shell);
If you are just deploying to a single platform (like Windows) then tossing a single SWT jar plus the native library. If you are targeting multiple platforms then this becomes a pain.
So those are the two choice: deal with the AWTUtilities risk or use the SWT_AWT bridge.
EDIT:
Some time has passed and Java 7 is out. There is documentation on the officially supported way to accomplish this in the Java Tutorials. The section "How to Implement a Shaped Window" at the bottom gives an example. This of course assumes you can mandate Java 7
You don't need a new Frame object, you can only use
this.setShape(shape);
or your frame name like this
Frame1.setShape(shape);
a lot of AWT methods has been applied to java.awt.Frame
It is possible to access bits of MATLAB's internal java code to programmatically change MATLAB itself. For example, you can programmatically open a document in the editor using
editorServices = com.mathworks.mlservices.MLEditorServices;
editorServices.newDocument() %older versions of MATLAB seem to use new()
You can see the method signatures (but not what they do) using methodsview.
methodsview(com.mathworks.mlservices.MLEditorServices)
I have a few related questions about using these Java methods.
Firstly, is there any documentation on these things (either from the Mathworks or otherwise)?
Secondly, how do you find out what methods are available? The ones I've come across appear to be contained in JAR files in matlabroot\java\jar, but I'm not sure what the best way to inspect a JAR file is.
Thirdly, are there functions for inspecting the classes, other than methodsview?
Finally, are there any really useful methods that anyone has found?
There is no official documentation nor support for these classes. Moreover, these classes and internal methods represent internal implementation that may change without notice in any future Matlab release. This said, you can use my uiinspect and checkClass utilities to investigate the internal methods, properties and static fields. These utilities use Java reflection to do their job, something which is also done by the built-in methodsview function (I believe my utilities are far more powerful, though). In this respect, I believe we are not crossing the line of reverse-engineering which may violate Matlab's license.
If you are looking for documentation, then my UndocumentedMatlab.com website has plenty of relevant resources, and more is added on a regular basis so keep tuned.
I am also working on a book that will present a very detailed overview of all these internal classes, among other undocumented stuff - I hope to have publication news later this year.
I am an eclipse fan. If you use that as your IDE, the jar can be imported into one of your projects and you can inspect the methods in there.
To find out more about java objects, I use uiinspect.
The only place I know that is documenting the Matlab hidden Java stuff is Undocumented Matlab by Yair Altman. His site lists plenty of very useful tricks. Being able to use Java to format text in list boxes has come in very handy for me, for example.
EDIT
The man has spoken. Listen to him, since I don't think there's anyone outside MathWorks who knows more about Matlab's internal java code.
Undocumented Matlab is a great place to start looking.
The compiler display warnings if you use Sun's proprietary Java classes. I'm of the opinion that it's generally a bad idea to use these classes. I read this somewhere. However, aside from the warnings are there any fundamental reasons why you should not use them?
Because they are internal APIs: they are subject to change in a undocumented or unsupported way and they are bound to a specific JRE/JDK (Sun in your case), limiting portability of your programs.
Try to avoid uses of such APIs, always prefer a public documented and specified class.
The JDK 6 Documentation includes a link titled Note About sun.* Packages. This is a document from the Java 1.2 docs, so references to sun.* should be treated as if they said com.sun.*
The most important points from it are:
The classes that Sun includes with the
Java 2 SDK, Standard Edition, fall
into package groups java.*, javax.*,
org.* and sun.*. All but the sun.*
packages are a standard part of the
Java platform and will be supported
into the future. In general, packages
such as sun.*, that are outside of the
Java platform, can be different across
OS platforms (Solaris, Windows, Linux,
Macintosh, etc.) and can change at any
time without notice with SDK versions
(1.2, 1.2.1, 1.2.3, etc). Programs
that contain direct calls to the sun.*
packages are not 100% Pure Java.
and
Each company that implements the Java
platform will do so in their own
private way. The classes in sun.* are
present in the SDK to support the Sun
implementation of the Java platform:
the sun.* classes are what make the
Java platform classes work "under the
covers" for the Sun Java 2 SDK. These
classes will not in general be present
on another vendor's Java platform. If
your Java program asks for a class
"sun.package.Foo" by name, it may fail
with ClassNotFoundError, and you will
have lost a major advantage of
developing in Java.
Try running your code with a non-Sun JVM and see what happens...
(Your code will fail with a ClassNotFound exception)
Yes, because nobody guarantees that these classes or API will be the same with the next Java release and I bet it's not guaranteed that those classes are available in Java versions from other vendors.
So you couple your code to special Java version and loose at least portability.
Sun's proprietary Java classes are part of their Java implementation not part of the Java API their use is undocumented and unsupported. Since they are internal they can be changed at any time for any reason that the team working the Sun JVM decides.
Also Sun's Java implementation is not the only one out there! Your code would not be able portable to JVMs from other vendors like Oracle/BEA and IBM.
Here is Oracle's answer: Why Developers Should Not Write Programs That Call 'sun' Packages
I recently had a case that showed a real-world problem you can hit when you use these classes: we had code that would not compile because a method it was using on a sun.* class simply did not exist in OpenJDK on Ubuntu. So I guess when using these classes you can no longer say things like 'this works with Java 5', because it will only work on a certain Java implementation.