I have made a program that consist of a few classes a class that extends however one class doesn't produce any JavaDoc or appear in the program tree. It is declared like this:
class myClass extends anotherClassOfMine {
}
Is there something special I need to add to anotherClassOfMine to ensure that the JavaDoc is created for myClass?
TIA
As mentiones in the comments, by default Javadoc only includes public and protected elements. Your class not being public, Javadoc thinks it is not intended to be documented.
You can either make your class public (adding public), or change Javadoc's behaviour by adding one of the access options -package or -private. Other values are -public or -protected (the default).
(Of course, you should also add some actual documentation, but one of the changes above should be enough so your class will show up.)
Related
I am new to Java. Maybe the question is a bit naive.
For example, I have a pkg1, in which there are 2 Java files: f1.java and f2.java
As the title, I feel it is reasonable
to use a package-private-top-level class for f1,
then use a public-top-level class for f2,
then the outside of pkg1 can still access f1 via f2.
I can even have f3, f4... ..., which are all using package-private class as their top-level class. Then f2.java will become a package-interface file for the rest of files in pkg1.
So, why is the fact that a top-level class must be public? Just to prevent from unnecessary complexity?
According to Oracle Java tutorial, public isn't the only possible modifier for top-level class:
A class may be declared with the modifier public, in which case that class is visible to all classes everywhere. If a class has no modifier (the default, also known as package-private), it is visible only within its own package
So, basically, there's no problem in making some classes protected or package-private if your design requests it.
Term 'top-level class' actually exists in Java as well as terms 'inner class' and 'nested class', I suggest you to take a look on this page to clear some basics of java class hierarchy.
why is the fact that a top-level class must be public?
A "top level" class in Java is just a class that isn't a nested class (a class inside another class — JLS§8). They are not required to be public.
You may be thinking of applications that are run via the java tool (not all are!). The class meant to be used as the entry point for the java tool is usually shown as public in examples, but it isn't required to be. It is required to have a public static void main method accepting a String array, but the class itself doesn't have to be public.
A top level class should be public because a public class can be used any where in the java universe,but if you declare a class private or protected then its sole purpose is lost declaring a class private will not allow this class to be visible to any other class and marking it is protected will also do the same thing.Its always recommended to make a class default or public.
I have two classes in my app with identicall names, I cannot rename them, on of them is from packageA second from packageB, the name of this class is State, and I have to use it in one place in my program like this:
Map<Integer,Set<org.omg.PortableServer.POAManagerPackage.State>>
is there any way (but using this class) to make this somewhat more readable(to shorten it somewhat)?
Possibly derive from one of the classes to disambiguate. For example, in POAState.java:
import org.omg.PortableServer.POAManagerPackage.State;
public class POAState extends State {}
then:
Map<Integer,Set<POAState>> my_map;
Create wrapping class that will have only Set<org.omg.PortableServer.POAManagerPackage.State> and all the needed Set methods.
usage in client:
Map<Integer,GoodWrappingSetName>
If you use the two different State classes in the same piece of code (*.java file), then the answer is "No", Java does not provide a short hand notation. You must be explicit and include the full package names to remove the ambiguity.
#dantuch has raised an interesting idea, but rather than wrap the class, if you can extend one of them, you can create an empty sub-class of State that simply defers all of it's implementation to the parent class.
public MyState extends State {
// no implementation required
}
Then you can then refer to MyState
I have file TestClass.java
package com.fido.android.sample.dsm.SoftPin.Core;
public class TestClass
{
public int mValue1;
public String mValue2;
}
Now in this file (TestClass.java) I want to declare one more class, but when I write for example:
public class SecondClass
{
// Class members goes here.
}
Compiler do not allow me to do that, if I remove public everything is Okay, but I can use SecondClass only in the TestClass.java, I can't write
SecondClass sc = new SecondClass();
out of TestClass.java class. Now I want to know if there is a way to do such thing, to have two classes in the same file and to use them from everywhere (not inner classes).
Question is: Why would you want to declare a second public class within the same Java class file? It is a rule in Java that each public class must be declared in a single class file - except for nested classes like Graham Borland pointed out.
Short answer: You can't.
That's how Java works.
You can only declare a single public class per file, with the class name the same as the file name.
You can use inner-classing as Graham suggested, or better yet, move the second class in a new file.
If you have SecondClass inside TestClass (i.e. nested inside the class definition), with public visibility, then you can refer to TestClass.SecondClass everywhere.
No, you can't, if the compiler chooses to enforce this rule from the Java Language Specification, section 7.6:
When packages are stored in a file system (§7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:
The type is referred to by code in other compilation units of the package in which the type is declared.
The type is declared public (and therefore is potentially accessible from code in other packages).
This restriction implies that there must be at most one such type per compilation unit.
So this is optional in that it's still "legal Java" to include more than one public top-level class in a single source file - but it's also valid for the compiler to reject it. In practice, I think every file-based Java compiler I've ever used enforces this rule.
Now you could try to find a different compiler if you really wanted, but there's a reason for this: Java programmers are used to finding the source code for a public top-level type (and usually any top-level type) in a source file with the same name.
To ask a return question provocatively: why do you want to make your source code hard to navigate?
You cannot.
What you can do is to have inner classes.
According to java conventions, A public class should be created in a separate file having same name as of class name.
So you cannot make two public classes in same file.
you can try either removing public from one class or making inner class.
Since public classes must have the same name as the source file , there can only one pulbic class inside a java file.
What's the reason of making top-level class non-public in Java?
Let's say we have Foo.java, there could be
class Foo {
}
or
public class Foo {
}
I understand that there will be some class - visibility issues with the former example (probably it won't be visible from other packages). But anyway, are there any reasons why someone may want to do as in the first code sample?
UPD: What cons I see in the former solution: nobody cares that it's non-public. That class can be simply extended by some other public class in the same package later, then, non-public part of the class may bring you visibility/access issues.
Here is an example.
No one needs to know about existence of our ConcreteDocument.
DocumentIF.java
public interface DocumentIF {
}
ConcreteDocument.java
class ConcreteDocument implements DocumentIF {
}
DocumentFactory.java
public class DocumentFactory {
public DocumentIF createDocument() {
return new ConcreteDocument();
}
}
Typically, you make a class package-private because you don't want the class to be used outside the package. When a top-level class isn't public, it's private to the package.
Say you have a package with a number of classes that must communicate the same sort of data with one another. But this data structure is an implementation detail and so you don't want it being used by user code. Making the transfer class package private maintains this sort of package level encapsulation.
I understand that there will be some class - visibility issues with the former example (probably it won't be visible from other packages).
That seems to me to be reason enough to use it if you want to keep the class private to that one package.
Just noticed another use! It seems you can only have one public top-level class per code file, but any number of non-public top-level classes. Haven't verified it personally, but if true that could be quite useful to prevent cluttering your project folder and to group classes with related functionality that aren't needed outside of the package.
Classes without a public or protected modifier are only visible inside the package they reside. If you think of components and interfaces there is a reason for leaving out the public modifier. Let's say you have a public class MyCompontent that internally uses other classes, but does not want to publish those to the outside world (users of the component) it makes sense to leave out the visibility modifier.
It is considered good design to keep the visibility of a class to the most minimum required. The reasons that I can think of:
The class can easily change in the future without causing breakages in external packages as the external packages do not have access to the class. In this regard it might be even better to start off a class by making it a private inner class.
The class being package visible cannot be extended by classes in external packages. This again makes it easier for this class to change without causing breaking changes in external packages. If this class was not meant to be extended then it would be even better to make this final.
A public visible class becomes a part of the exported API of your library. If you are a library designer, it is better to keep your exported API as small as possible because you do not want to confuse your consumer with un-necessary classes/details. Item 1 would again hold good in this case.
The book "Effective Java" by Josh Bloch is an excellent reference for Idiomatic Java code and design.
as for my observation when the class itself is having default access modifier, what is the use of having public methods in it. the java compiler could have stopped using public methods in default class. is there any reason for that?
The non-public class might implement a public interface. This would mean that classes outside of the package could not create an instance of this class or create references of that type, but they would still be able to invoke methods on it if passed an instance.
For example, a public factory class might create an instance of an non-public class in its package and return it.
One reason: if your class implements some interface (or extends some abstract class with abstract public methods), then you may not reduce the visibility of those implemented methods.
It is a beautiful combination of Security and Usability packed in one.
I would mark a Class with default access if I want it to have a, well, package access (so that no other package can use it or better change the code) and marking a method public, I am making the method accessible to all other classes regardless of the package they belong to.
How does that help? A class which is secure enough to perform all the complex code implementation and usable enough to give the output to the user who wants to use it.
How can anyone use that? Well you write code to help them use it by creating a public class which extends this default class. You Instantiate this public Subclass in any package (after importing of-course) and this has all the methods marked public.
You have a class which does your magic which everyone can use without giving anyone else a hint of how you got it done!