I am quite new to Java, and need to work on a project requiring using open source software. I am very confusing about understanding those Java API's documentation.
As an example, can you show me how to use the related java class, RemoteXmlSimpleSearchEngineBase, based on its Java API.
Please refer to this link
http://download.carrot2.org/stable/javadoc/org/carrot2/source/xml/RemoteXmlSimpleSearchEngineBase.html
I am very interested in this derivation process, so that I can use other java classes based on reading its API documentation. Thanks.
Often the JavaDoc doesn't explain the general concept of a library but just the API for that class. It might contain more useful information (like the JDK JavaDocs do), but in general you should try to get a user manual, reference or getting started guide.
From the JavaDoc you can still learn a few things:
what interfaces are implemented
which directly known subclasses/implementors exist
you see that the class is abstract
which methods are added/overridden by that class
which methods are added
pre-/postconditions of the methods and its parameters (sometimes not listed)
...
However, you often don't get the general concept or when a method is called, how to configure a class for various use cases etc. You simply can't put that all into an API documention.
Maybe you should take a look to the project documentation:
http://project.carrot2.org/documentation.html
You have some examples and lot of information.
What I often find useful when trying to get an overview over some API are the class/interface trees, and even more the "Usage" pages - they show which other classes/interfaces use this class/interface in their API. This shows how to get some type of object (by finding return values), or what to do with some object (except from using its methods itself).
Sadly, the latter ones are not generated by default (and also missing in the example in your question).
Very often, the JavaDoc overview page will have some overview of the API and code examples. This is actually the case with Carrot2 JavaDoc:
http://download.carrot2.org/stable/javadoc/overview-summary.html#overview_description
Related
We are migrating a system written in C to Java and must retain existing processes (no debate). We currently "embed" compile-time information into the C application using the C preprocessor, for example:
cc -o xxx.o -DCOMP_ARG='"compile time arg"' xxx.c
The xxx.c file can then use "COMP_ARG" and its value will be embedded in the code and we have little worry about it being changed inadvertently.
We realize Java likes to use properties files, however, our requirements are such that some information ** ** be embedded in the code, so properties files are not an option - these certain values cannot be specified at runtime. To illustrate the point, such data could be a date-stamp of when the file was compiled, but the exact data is irrelevant to the question.
We are looking for a way to specify at compile time various values that are available to the Java code. We are quite aware that Java does not have a pre-processor as does C, so the mechanism would be different.
Our current solution is using a code generation step (Maven), which does work, however, Eclipse is wreaking havoc trying to deal with the source files so that we had turn off "Build Automatically". We really want to find a more robust solution.
We appreciate any help, thanks.
The xxx.c file can then use "COMP_ARG" and its value will be embedded
in the code and we have little worry about it being changed
inadvertently.
...our requirements are such that some information be embedded in the
code....
We are looking for a way to specify at compile time various values
that are available to the Java code. We are quite aware that Java does
not have a pre-processor as does C, so the mechanism would be
different.
It seems that the best way to solve this problem would be to make use of annotations in your code.
In Java, annotations are a kind of interface declaration, but they do not enforce a behavioral contract with an implementing class. Rather, they are meant to define a contract with some external framework, preprocessor, or with the compiler itself. Annotations are used extensively in Java EE 5.0 (and later) to specify configuration and behavior to the framework within which the developer's code runs. Annotations are also used extensively by the JavaDoc documentation processor. Here, the annotations in the doc comments allow you to specify and format the information which you intend to appear in the documentation when the JavaDoc processor runs.
Annotations can be defined to be accessible at runtime. In such a case, the primary mechanism for accessing annotations is the Java Reflection facility. For example, annotations with a retention policy of RUNTIME and defined on a class, can be accessed through that class's corresponding Class object:
Class myCls = MyClass.class; // the "class literal" for MyClass
Annotation[] annotations = myCls.getDeclaredAnnotations();
Annotations can include arguments for parameters to allow for more flexibility in configuration. The use of annotations is most convenient when the code itself can be so annotated.
A quick tutorial on how annotations are defined and used in Java is available here: https://docs.oracle.com/javase/tutorial/java/annotations/
I'm going to post my own answer which seems to be "Can't be done" - what can't be done, apparently, is provide at compile time to Java, a set of parameters that gets passed to the program at execution time. The solution appears to be to continue with what I am doing which is to update a Java source file with the compile-time data and figure out how to coax Eclipse to stop over-writing the files.
Thanks to everyone who commented.
Java 7 introduces a great API for writing custom file systems. Consider a use case where I don't want to implement a new file system, I just want to tweak the behavior of the existing one. For example, flip every bit that is written/read from it.
It seems to me that the current jdk just does not have the appropriate facilities for this. AbstractFileSystemProvider, the provider that WindowsFileSystemProvider extends is package-private so I can't reuse it. I didn't even find the concrete implementation for Linux.
Problem #1: There is no useful abstraction of the current file system for extension.
Let's assume I extend only for Windows. WindowsFileSystemProvider is public, so I can actually easily override the newByteChannel and be done with it. But Alas!
Problem #2: WindowsFileSystem is not public, so I actually have to code an entirely new FileSystem just to introduce a new Provider.
Am I missing something or is this feature completely raw and not ready to be used by application writers?
After contacting core-libs-dev in openjdk, I got the following answer:
The service provider interface allows you to replace the default provider or interpose on it (see the FileSystems.getDefault docs for the details on how this is configured). When you interpose on the default provider then you have the opportunity to do your customization although it can be tricky to ensure that you get all the delegation right. As a starting point then look at the PassThroughFileSystem in jdk/test tree, this is a provider used by some of the tests and may be what you are looking for.
The PassThroughFileSystem is a nice reference implementation that demonstrates how one can implement a custom provider with proper delegation to the default one. That being said, in my opinion the problem is still there but at least we have a better starting point.
In software development we are all using the libraries by software providers. Consider in class A there are four functions viz., x,y,z. I just want my development team to avoid using the function x. So instead of telling them not to use, I found an idea. Inherit the class and override all the functions and for the function x an unsupportedmethod exception is thrown and for the rest I'm calling the super methods. There also I found a problem, developers can use the base class A directly, how to avoid the class A being used directly. I found a similar functionality in OSGi, the lib bundles can be brought in and then not exported and so on. Is there are any way to achieve this is java?
I suppose code reviews exist for these reasons. Consider situation where you can not edit the source of a third party, what would you do ? Like Siddharth says, sub class it and throw a meaningful exception and document it with a clear reasons. If someone is using base class even after that, mostly it may not out of ignorance,but it may out of curiosity. That kind of thing can be appreciated personally and for learning, but for the project sake developer has to follow the guidelines.
I think simply telling your developers what to do is preferred over a complex software solution. Sometimes the simple thing is better.
But, if you insist on going down this path, you can enforce your architecture standards using aspects if you're a Spring user. Weave the offending methods with an aspect that throws an exception if they're called.
You can edit library class file in hex editor and modify its access modifier from public to package private. Also you can rename it and then use inheritance to wrap this class. Here you can find class file specification. Once I've tried this technique to substitute jdbc driver class with wraper class that provide some additional logging and other useful tricks.
There is a variety of tools that check source code for adherence to certain rules, such as formatting, dead code, naming conventions for variables etc. Popular ones for Java include the Maven Enforcer plugin, checkstyle and PMD.
These might allow you to write a rule that forbids certain method calls. Then you could check automatically at compile time. As far as I can tell, unfortunately none of the tools above support "illegal method calls" out-of-the-box; however, at least for PMD writing new checks is fairly simple.
As good as the Java API is, I need to change the code of some classes in the default API packages (for example java.util.Scanner) for a project I am working on.
Ideally, I would extend the classes I am interested and create my own sub-classes, but the classes I want to extend are declared 'final'. How do you suggest I do this? Will I get into trouble with the compiler if I customize the source code of these packages?
If you can, you should rather wrap and delegate, as suggested in another answer. See the Adapter Pattern.
But there are of course ways to do this if you really need it.
A straightforward approach is to simply modify the code in downloaded sources and substitute your own version of a jar in the classpath.
Another option is to use aspect-oriented programming techniques, likely with AspectJ to intercept and modify calls as needed.
It might also be possible to hack together a solution using reflection and home-grown classloaders, but it will be painful to code.
All of these are however quite risky if you don't know what you're doing. Frequently classes are made final for good reason.
If you tell us more specifically what it is you're hoping to change, we might be able to provide assistance in avoiding what you currently think you need.
you really cant extend a final class..
if u really want to add a functionality by extending a class you can do it by modifying class src. from JDK and save it as your own class and use it.
Don't do that. Write your own code which wraps around the original scanner and use that. To update internal packages, there is an endorsed directory property which you can provide at runtime.
Never do it! Never change core classes. If class is final - use composition not inheritance.
I am current using Seasar2 Framework on a project that I am in. The framework is quite popular here in Japan but I am having problem in finding English documentations. Even on their official English translation site, they just discuss that the framework use Dependency Injection and AOP.
I was intrigued with the way they use it in one of their component S2Dao. Basically you only need to create interface DAO class and the framework automatically, changes the code on runtime and creates intermediate class that get called in the middle. Hence DB transactions codes are automatically added to the class. I was wondering, is there any step by step explanation on how this is done? Can java change code on runtime and change the method on runtime?
Are good reference on how this is done? I just want to know how the framework is doing this.
Yes, it is possible to do dynamic implementations of an interface at runtime, and to manipulate the compiled bytecode also.
Java provides a built-in mechanism to implement interfaces at run-time, called dynamic proxy classes.
There are also good libraries like cglib or javassist, that allow you not only to implement interfaces, but also to extend classes and to manipulate bytecode at run-time (to change the behavior of a method, for example). Frameworks like Spring and Hibernate use libraries like these to make their magic, so your framework may be using some of these also.
NOTE: If you are curious, these libraries can "tweak" the bytecode because instead of using the default ClassLoader of the JVM, they load your classes using their own ClassLoader, so they have total control of every single byte of the loaded class, and they can do whatever they want with them :).