I'm using javadocs generated by the javadoc Ant task to document a web service, and I want to exclude some constructors from the output. How do I do that?
There is no way to do this for public methods. The standard practice (even in quite a few JDK classes) is to indicate that the method or constructor is not meant for public use.
There is a plan to add an #exclude tag in the future:
#exclude - for API to be excluded from
generation by Javadoc. Programmer
would mark a class, interface,
constructor, method or field with
#exclude. Presence of tag would cause
API to be excluded from the generated
documentation. Text following tag
could explain reason for exclusion,
but would be ignored by Javadoc.
(Formerly proposed as #hide, but the
term "hide" is more appropriate for
run-time dynamic show/hide
capability.) For more discussion, see:
Feature Request #4058216 in Developer
Connection.
Isn't excluding something public from your documentation just a variation on "security through obscurity" (or rather, "documentation through obscurity")? If the constructor is part of your code's API, it's available for them to use. If they find out about it and use it, is that their fault (since you made it public in the first place)?
If you can change the constructor's visibility or remove it altogether, I would go for that. If you cannot remove it from the API, make it known in the Javadoc for the constructor that it's not intended for use via web service. That way you've established a contract with users of your API, informing them not to use it.
It's better to document that it should not be used instead of not documenting it at all (if it's public). Not documenting it adds risk that it gets inadvertently used, and then the client code using it breaks when you change the implementation.
See the relevant Javadoc FAQ entry.
There is currently no Javadoc option
to hide, exclude or suppress public
members from the javadoc-generated
documentation.
It would appear this is not possible in the vanilla Javadoc, but some workarounds are offered.
Currently the simplest solution is to start the javadoc comment with #deprecated, and then pass -nodeprecated to the javadoc command. Of course, this may not be acceptable if you have actual deprecated items which you nevertheless want to include in the documentation.
Change the method access level of the method, then use the use the javadoc task's access-level filtering attributes, private, package, etc. Only do this if it makes sense in your code, though, e.g., method that had inappropriately loose access levels.
For constructors, for example, you could reduce the access level to package, then create a factory class in the same package that provides construction access outside the package. The factory class can be easily filtered from the javadocs. Kind of hacky, but it works.
Give Chris Nokleberg's ExcludeDoclet a try:
http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html
I've just been experimenting with it and it seems to do the trick.
The closes I got is to use Doclava, which has the #hide tag you can specify in method documentation.
Related
Simple question here. Is there any point in applying javadocs to methods in a javafx application.
For starters - the majority of my method headers are formatted as private (with #FXML annotation).
I am using some public methods - but what is the point in javadocs if the end user uses a GUI to interact with the application and my application isn't an API? Obviously, all my methods are concisely commented - but I don't see what benefit javadocs will have for users or future developers of the code.
Am I wrong? If so, I'd really appreciate your views on this.
Many thanks.
Please take a look at https://softwareengineering.stackexchange.com/questions/85910/is-it-wrong-not-to-create-javadoc-for-my-code
In theory, meaningful documentation is never bad, and therefore every method you can document in a meaningful way should be documented.
In practice, it comes down to who the "audience" for the documentation is, to team-agreement, and to personal choice.
Things to consider are:
Your audience can be a maintenance developer, which, nevermind other persons, may be yourself, after 3 years without working or visiting the project, and after you have forgotten the details of how it all works.
In case of Javadoc and similar documentation tools and standards, even for private methods (usually not outputted to external doc files by default), many IDEs support Javadocs (or similar) and implement extra-features based on them. NetBeans, for example, can display tooltips containing the types, names, and if you documented them, purposes of classes, methods, and input and output parameters and vars. Eliminating the need to open files and/or look at source-code inline-comments if and when you forget something.
For framework code, I always Javadoc all public and protected members. For application code, I generally don't bother with Javadoc comments, but I do use inline comments to explain what a method is doing.
For private methods (whether framework or app code), I don't use Javadoc at all, since they aren't included in the Javadoc output by default. I do use inline comments for private members, though.
I have a class which behavior I would like to change. I need to replace private method with another realization. Common reflection techniques allow to modify private variable or to invoke private methods. But I find little information about replacing entire methods.
I presume that there are advanced techniques to do so. May be its impossible with standard java reflection but there are probably other tools to recompile byte code in runtime.
Modify & replace:
One option is to mask the class with a modified copy (modify code, recompile code, add modified classes to the classpath before patched classes), similar to the approach used here to inspect how a normally unavailable method works.
If you do not have sources to modify, you can "reverse" almost any .class file into more-or-less readable source code using decompilers. Notice that, depending on licensing, you may not have permission to do so and/or to redistribute your changes.
Patch via agent:
You can also patch the methods using the -javaagent:<jarpath>[=<options>] commant-line option. The "agent" is a jar that gets to modify loaded classes and alter their behaviour. More information here.
Mock:
If you have control over where the methods are called, you can replace the target instance with a stubbed version. Libraries such as Mockito make this very, very easy:
LinkedList mockedList = mock(LinkedList.class);
// stubbing appears before the actual execution
when(mockedList.get(0)).thenReturn("first");
Even though Mockito does not support mocking private methods natively (mostly because it is considered bad manners to look at other classes' privates), using PowerMock allows you to do so (thanks, #talex).
You can't replace method in runtime (at least without hack into JVM). But you can replace whole class. There are several way to do it. For example you can use thing called "aspect".
But from my experience I can say that if you need to do this you have wrong turn somewhere in beginning of you way.
Maybe you better make one step back and look at whole picture
Instead of going for advanced techniques, there is a simple trick to achieve this.
If you class is part of an open-source jar, get source code of this class file from grepcode.com. Change the method that you want to change and compile it. And update your jar file/classpath with this updated class file.
There are a couple of cases where I would like to add/modify just one method of GWT's implementation of a JRE class (see Class.isInstance or System.arraycopy, for example).
As GWT is improved, other methods in the same classes might be updated, so I would rather not just take the current implementation of the entire class, modify it, and then stick it in a super-source directory, as I would then have to check for significant changes in these files every time a new version of GWT is released.
I would much prefer to just extend the already existing GWT implementation and only override the one method I would like to change. Is that possible somehow?
This might help:
Deferred Binding Using Replacement
The first type of deferred binding uses replacement. Replacement means overriding the implementation of one java class with another that is determined at compile time. For example, this technique is used to conditionalize the implementation of some widgets, such as the PopupPanel. The use of for the PopupPanel class is shown in the previous section describing the deferred binding rules. The actual replacement rules are specified in Popup.gwt.xml, as shown below:
http://www.gwtproject.org/doc/latest/DevGuideCodingBasicsDeferred.html
I have a Java class which have some confidential information which I don't want to provide to any unauthorized class.
I want to access this class in some packages (classes from this packages are going to utilize confidential information), So that my secure class should be accessible in these packages.
Is there any way where I can check if caller of method is a authorized class from authorized package or not?
I know public/private/default all things (so please don't ask me to use it), but those are not useful here, because I want a class to be accessible in some packages(not one/same).
I feel that you are going in the wrong direction. It might be a design problem.
The security requirement is your business logic. You should implement your security policy somehow, not rely on the java language level visibility modifier or caller package names. since if you give your jar to someone, he can anyway get access to your "confidencial" class.
And moreover, a class is a type, something abstract. it should not contain "data". well sure sometimes conf information was written as static variable etc. However if some data is sensitive, it should not be written in class. It could be stored in database or encrypted file and so on. Once a request to the sensitive information comes, you check your implemented security policy, if it is allowed to access those data.
just my 2cents
The visibility modifiers in Java are not a security tool, but an OO design tool. Whatever you might do, if someone uses your class, it can access any private members of any class using reflection.
If your objects contain confidential information, leave these objects in your secure server.
You can create an Exception (no need for it to be thrown) and use the getStackTrace() to analize the call stack. I always found it ugly, though.
That said, anything that you put in a client machine is vulnerable to that machine; if you have something really confidential protect it in your server; make it available only as a service.
You can use the proxy pattern, implemented by the Proxy class in Java - it is designed exactly for your purpose.
Here is a how-to.
EDIT : AFAIK, you cannot use the regular Proxy mechanism for static methods, as the proxy and the proxied class must implement a common interface. However, there are more advanced tools, which may help you like javassist. Unfortunately I'm not familiar with it myself.
You might be able to leverage aspectj here. It's theoretically possible to intercept the call to a given classes' methods based on the current flow scope, and have the aspect throw an exception or something. I'm no aspectj expert though, but the "cflow" pointcut qualifier would be your most likely bet. Maybe something like this
! cflow(call(* com.mycom.AllowedClient.*))
I haven't tested this kind of pointcut, but i believe it would work.
You'd probably want compile time weaving in this case though (as opposed to load time weaving).
As a side note, i agree with some of the others that i think this is the wrong approach to take. You protect data. You protected function access based on logged in user permissions. You typically don't protect function calls from other classes.
Guideline 4-2 / EXTEND-2: Limit the accessibility of packages
Containers may hide implementation code by adding to the package.access security property. This property prevents untrusted classes from other class loaders linking and using reflection on the specified package hierarchy. Care must be taken to ensure that packages cannot be accessed by untrusted contexts before this property has been set.
This example code demonstrates how to append to the package.access security property. Note that it is not thread-safe. This code should generally only appear once in a system.
private static final String PACKAGE_ACCESS_KEY = "package.access";
static {
String packageAccess = Security.getProperty(PACKAGE_ACCESS_KEY);
Security.setProperty(PACKAGE_ACCESS_KEY,
(packageAccess == null || packageAccess.trim().isEmpty()
? "" : packageAccess + ",")
+ "xx.example.product.implementation.");
}
Here's the scenario. As a creator of publicly licensed, open source APIs, my group has created a Java-based web user interface framework (so what else is new?). To keep things nice and organized as one should in Java, we have used packages with naming convention
org.mygroup.myframework.x, with the x being things like components, validators, converters, utilities, and so on (again, what else is new?).
Now, somewhere in class org.mygroup.myframework.foo.Bar is a method void doStuff() that I need to perform logic specific to my framework, and I need to be able to call it from a few other places in my framework, for example org.mygroup.myframework.far.Boo. Given that Boo is neither a subclass of Bar nor in the exact same package, the method doStuff() must be declared public to be callable by Boo.
However, my framework exists as a tool to allow other developers to create simpler more elegant R.I.A.s for their clients. But if com.yourcompany.yourapplication.YourComponent calls doStuff(), it could have unexpected and undesirable consequences. I would
prefer that this never be allowed to happen. Note that Bar contains other methods that are genuinely public.
In an ivory tower world, we would re-write the Java language and insert a tokenized analogue to default access, that would allow any class in a package structure of our choice to access my method, maybe looking similar to:
[org.mygroup.myframework.*] void doStuff() { .... }
where the wildcard would mean any class whose package begins with org.mygroup.myframework can call, but no one else.
Given that this world does not exist, what other good options might we have?
Note that this is motivated by a real-life scenario; names have been changed to protect the guilty. There exists a real framework where peppered throughout its Javadoc one will find public methods commented as "THIS METHOD IS INTERNAL TO MYFRAMEWORK AND NOT
PART OF ITS PUBLIC API. DO NOT CALL!!!!!!" A little research shows these methods are called from elsewhere within the framework.
In truth, I am a developer using the framework in question. Although our application is deployed and is a success, my team experienced so many challenges that we want to convince our bosses to never use this framework again. We want to do this in a well thought out presentation of the poor design decisions made by the framework's developers, and not just as a rant. This issue would be one (of several) of our points, but we just can't put a finger on how we might have done it differently. There has already been some lively discussion here at my workplace, so I wondered what the rest of the world would think.
Update: No offense to the two answerers so far, but I think you've missed the mark, or I didn't express it well. Either way allow me to try to illuminate things. Put as simply as I can, how should the framework's developers have refactored the following. Note this is a really rough example.
package org.mygroup.myframework.foo;
public class Bar {
/** Adds a Bar component to application UI */
public boolean addComponentHTML() {
// Code that adds the HTML for a Bar component to a UI screen
// returns true if successful
// I need users of my framework to be able to call this method, so
// they can actually add a Bar component to their application's UI
}
/** Not really public, do not call */
public void doStuff() {
// Code that performs internal logic to my framework
// If other users call it, Really Bad Things could happen!
// But I need it to be public so org.mygroup.myframework.far.Boo can call
}
}
Another update: So I just learned that C# has the "internal" access modifier. So perhaps a better way to have phrased this question might have been, "How to simulate/ emulate internal access in Java?" Nevertheless, I am not in search of new answers. Our boss ultimately agreed with the concerns mentioned above
You get closest to the answer when you mention the documentation problem. The real issue isn't that you can't "protect" your internal methods; rather, it is that the internal methods pollute your documentation and introduce the risk that a client module may call an internal method by mistake.
Of course, even if you did have fine grained permissions, you still aren't going to be able to prevent a client module from calling internal methods---the jvm doesn't protect against reflection based calls to private methods anyway.
The approach I use is to define an interface for each problematic class, and have the class implement it. The interface can be documented solely in terms of client modules, while the implementing class can provide what internal documentation you desire. You don't even have to include the implementation javadoc in your distribution bundle if you don't want to, but either way the boundary is clearly demarcated.
As long as you ensure that at runtime only one implementation is loaded per documentation-interface, a modern jvm will guarantee you don't suffer any performance penalty for using it; and, you can load harness/stub versions during testing for an added bonus.
The only idea that I can think in order to supply this missing "Framework level access modifier" is CDI and a better design.
If you have to use a method from very different classes and packages in various (but few) situations THERE WILL BE certainly a way to redesign those classes in order to make those methods "private" and inacessible.
There is no support in Java language for such kind of access level (you would like something like "internal" with namespace). You can only restrict access to package level (or the known inheritance public-protected-private model).
From my experience, you can use Eclipse convention:
create a package called "internal" that all class hierarchy (including sub-packages) of this package will be considered as non-API code and could be changed anytime with no guarantee for your users. In that non-API code, use public methods whenever you like. Since it is only a convention and it is not enforced by the JVM or Java compiler, you cannot prevent users from using the code, but at least let them know that these classes were not meant to be used by 3rd parties.
By the way, in Eclipse platform source code, there is a complex plugin model that enforces you not to use internal code of other plugins by implementing custom class loader for each plugin that prevents loading classes that should be "internal" in these plugins.
Interfaces and dynamic proxies are sometimes used to make sure you only expose methods that you do want to expose.
However that comes at a fairly hefty performance cost, if your methods are called very often.
Using the #Deprecated annotation might also be an option, although it won't stop external users invoking your "framework private" methods, they can't say they hadn't been warned.
In general I don't think you should worry about your users deliberately shooting themselves in the foot too much, so long as you made it clear to them that they shouldn't use something.