We Keep Coding

Gradle javadoc hide specified method [duplicate]

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.

Perform AsyncTask inside Class

I have a method inside of a class called
ChopraWisdom.GetQuote()
that pulls in some data from the interwebs. To use it I have to use an AsyncTask in my activity. Thats fine and all, but my Activity code now gets cluttered with the AsyncTask code.
I was hoping that I could hide the AsyncTask in my Class and then create another method called
ChopraWisdom.GetQuoteAsync()
But I'm not sure how to pass in "Actions" (I come from a .Net background) in order to handle the various UI updating that needs to take place.
In C# I would define the method signature as something like:
ChopraWisdom.GetQuoteAsync(Action preExecute, Action postExecute, Action updateProgress)
Questions:
Does java have something comparable to 'Action'?
What is the acceptable pattern for 'wrapping' Async functionality like this in Java?
I like clean code, but am I being to picky here?
Please provide examples.
EDIT - Added Example class
public class ChopraWisdom
{
public string GetQuote()
{
//...do stuff and return a string
}
}

You should really think about using Loaders instead of AsynkTask(with android support lib).
If you still want to use AsyncTask in your situation best way would be to create new interface Action(something like https://github.com/ReactiveX/RxJava/blob/1.x/src/main/java/rx/functions/Action0.java)
You could use RxJava in your project and use all they have https://github.com/ReactiveX/RxJava/tree/1.x/src/main/java/rx/functions
You could use https://github.com/evant/gradle-retrolambda in combination with (2) option to provide C# like lambdas in your java code.

Java does have something comparable to Action. It is called Function and only available in Java 8. The standard way for passing a function as parameter is to create an interface and provide it as a parameter. That way you can either pass in an instance of a class implementing that interface or create an anonymous class inline. You encounter the latter everywhere in Android (OnClickListener, etc ...)
I would highly recommend you to take a look at Android Annotations. It provides useful features like:
Dependency injection
View injection
OnClickListener via annotation
AsyncTask via annotation
...
And the best thing: everything is done at compile time through subclassing, therefore there is no performance impact and you can check what the framework is doing at any given point.
You are not too picky at all. Clean code is very important in Android development as you have to write a lot of boilerplate- / gluecode anyway.
Here are some other handy android frameworks that are definitely worth checking out:
GreenDao
Eventbus

Affecting Java classes without changing the code

I am using a Java library, with two classes Foo and FooConfig; I am unable to change the library code, but can read it. Here are the relevant functions of a Foo:
public class Foo
{
/** Install a configuration on this Foo */
void configure(FooConfig config);
/** Uninstall the current configuration */
void unconfigure();
}
The library creates Foos at times I can't control, and installs configurations shortly after creation. A Foo can only have on configuration at a time. I would like to use MyFooConfig, inherited from FooConfig, instead. Is there any way to intercept the configure call, or the FooConfig constructor, or anything like that to use my class instead?
My current solution is to get a reference to the Foo object shortly after its creation and configuration, uninstall the current configuration,and then install a MyFooConfig instead. This could work, but it causes several different problems (both with being a difficult solution to implement and with some inelegancies which can't be hidden from the user). Is there a better way, preferably using features of Java to intercept the constructor call to FooConfig, or the configure method, or something similar? The closest thing to an alternate solution I've found is to try to use a different ClassLoader to replace FooConfig with my own class behind the scenes, but I don't actually have access to the object that creates the FooConfigs so I don't think that's possible. Other things that looked promising but ultimately didn't pan out are proxy objects (I can't make the Foos be proxy objects), seeing if I could somehow get notified when a FooConfig was created without actually intercepting the constructor (so I could find its Foo and reconfigure it in a better way than I`m currently doing), and changing the library code itself (which, for various reasons, turns out to not be possible).
I don't know much about aspect-oriented programming, but it seems like it could help. Unfortunately, all the AOP Java tools seem to require special compilers, and I don't want to change the build process.

The missing "framework level" access modifier

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.

Extending GenericModel for Play Framework

I need to add some logic to GenericModel by means of extending it, but I understand that Play uses generics to enhance the GenericModel. What would be the right and most convenient way to extend this class?
I tried to do this, but some of the methods in GenericModel simply throw a UnsupportedOperationException exception, so this is clearly enhanced somewhere else.

Check out db.jpa.Model which also extends GenericModel.
If you intend to extends the GenericModel, I would do it in the models package. No need for an external module and it is best to avoid touching playframework core. You will have trouble updating it if you do.
But still, after a quick look at the source code, it seems that you are trying to modify JPA related code. What kind of logic are you talking about?

I've managed to get this working by means of reflection. Everything is now working 100%. :) Not really the best solution, but it works.