Develop Reference

When to use a different package?

I want to get into creating applications, however, I do not know when I should use packages. How should packages be used? How do you know what class to put in what package?

Except for really trivial programs that involve not more than one file, you should always use packages. A typical package structure is the following
com.<your_company>.<your_project>.<sub_system>....
or
org.<your_organization>.<your_project>.<sub_system>....
or (if you don't really belong to any organizations or companies)
<some_name>.<your_project>.<sub_system>....
where ... above indicate some more structure within your sub system. And
<some_name> is just some name that won't be easily in conflict with names that are used by other people. Don't worry. Even if you pick a name that
is already used by someone else, you won't be in trouble until the moment you
try to compile two packages of the same name together (obviously that
should not be allowed). So these names are all valid choices for <some_name>
playground
mytest
chapter1
tutorial
By convention, package names are always in lowercase. And in contrast, class names always start with an uppercase character. For example, in
com.google.gwt.core.client.EntryPoint;
the package name is com.google.gwt.core.client, and the classname is EntryPoint
A good way to learn is to see how other projects organize their packages and classes. Below I show some examples (which include both package names and class names):
org.hibernate.annotations.Cache;
org.hibernate.annotations.CacheConcurrencyStrategy;
com.google.gwt.core.shared.GWT;
com.google.gwt.core.client.EntryPoint;
com.google.gwt.user.client.Window;
com.google.gwt.user.client.Window.Location;
com.google.gwt.user.client.rpc.AsyncCallback;
com.google.gwt.user.client.ui.RootPanel;
com.smartgwt.client.util.DateUtil;
com.smartgwt.client.util.SC;
com.smartgwt.client.widgets.Canvas;
com.smartgwt.client.widgets.HTMLFlow;
com.smartgwt.client.widgets.layout.VLayout;
One more observation I would like to make is that package names
are often organized top-down (from big to small). This convention is
the reverse of the
convention of how Internet domain names are formed (from small to big).
In the above example, Google's GWT project has named their package as
com.google.gwt....
while Google's Internet domain names are in this form
....google.com
Many companies and organizations use the reverse of their domain names to form the prefix of their packages.

Use packages to seperate classes in your applications by concerns. This helps you in several ways:
avoid name conflicts between unrelated classes
group related classes together and isolate unrelated classes in different packages
which all should lead to a better maintainability of your application. If you can find reasonable names for your packages, you can get even a clue what purpose the classes in your package have.
You can read more about it in the official java tutorial. A very common use case is to seperate
application logic (also called model) from
presentation / gui code (often called view)
See how Java itself uses packages to seperate things:
java.lang.Math for computations
javax.swing, java.awt for gui frameworks
java.nio for buffered input/output

Packages are used in Java in order to prevent naming conflicts, to control access, to make searching/locating and usage of classes, interfaces, enumerations and annotations easier, etc.
If your program has a small amount of classes, like 3 classes
you may not have to separate them into packages.
Your classes are separated into packages in a logical way.
for example:
If you have a program that encryptes data, each of the encryption algorithms
can be separated into classes, and all of those encryption classes can be in the same package

Java good practices of which class should go where (packages) [duplicate]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 7 years ago.
The community reviewed whether to reopen this question last year and left it closed:
Original close reason(s) were not resolved
Improve this question
A little while ago, I saw a question answered here regarding the fine-grained organization of Java packages. For example, my.project.util, my.project.factory, my.project.service, etc.
Are there best practices with regards to the organization of packages in Java and what goes in them?
How do you organize your classes in your Java project?
For instance, a project I'm working on with a few people has a package called beans. It started out being a project containing simple beans, but it has ended up (through poor experience and lack of time) containing everything (almost). I've cleaned them up a little, by putting some factory classes in a factory package (classes with static methods that create beans), but we have other classes that do business logic and others that do simple processing (not with business logic) like retrieving a message for a code from a properties file.

I organize packages by feature, not by patterns or implementation roles. I think packages like:
beans
factories
collections
are wrong.
I prefer, for example:
orders
store
reports
so I can hide implementation details through package visibility. Factory of orders should be in the orders package so details about how to create an order are hidden.

Package organization or package structuring is usually a heated discussion. Below are some simple guidelines for package naming and structuring:
Follow Java package naming conventions
Structure your packages according to their functional role as well as their business role
Break down your packages according to their functionality or modules. e.g. com.company.product.modulea
Further break down could be based on layers in your software. But don't go overboard if you have only few classes in the package, then it makes sense to have everything in the package. e.g. com.company.product.module.web or com.company.product.module.util etc.
Avoid going overboard with structuring, IMO avoid separate packaging for exceptions, factories, etc. unless there's a pressing need.
If your project is small, keep it simple with few packages. e.g. com.company.product.model and com.company.product.util, etc.
Take a look at some of the popular open source projects out there on Apache projects. See how they use structuring, for various sized projects.
Also consider build and distribution when naming (allowing you to distribute your API or SDK in a different package, see the servlet API)
After a few experiments and trials, you should be able to come up with a structuring that you are comfortable with. Don't be fixated on one convention, be open to changes.

Short answer: One package per module/feature, possibly with sub-packages. Put closely related things together in the same package. Avoid circular dependencies between packages.
Long answer: I agree with most of this article

I prefer feature before layers, but I guess it depends on your project. Consider your forces:
Dependencies
Try minimize package dependencies, especially between features.
Extract APIs if necessary.
Team organization
In some organizations teams work on features and in others on layers.
This influence how code is organized, use it to formalize APIs or
encourage cooperation.
Deployment and versioning
Putting everything into a module make deployment and versioning
simpler, but bug fixing harder. Splitting things enable better
control, scalability and availability.
Respond to change
Well organized code is much simpler to change than a big ball of mud.
Size (people and lines of code)
The bigger the more formalized/standardized it needs to be.
Importance/quality
Some code is more important than other. APIs should be more stable then the implementation. Therefore it needs to be clearly separated.
Level of abstraction and entry point
It should be possible for an outsider to know what the code is about, and where to start reading from looking at the package tree.
Example:
com/company/module
+ feature1/
- MainClass // The entry point for exploring
+ api/ // Public interface, used by other features
+ domain/
- AggregateRoot
+ api/ // Internal API, complements the public, used by web
+ impl/
+ persistence/
+ web/ // Presentation layer
+ services/ // Rest or other remote API
+ support/
+ feature2/
+ support/ // Any support or utils used by more than on feature
+ io
+ config
+ persistence
+ web
This is just an example. It is quite formal. For example, it defines two interfaces for feature1. Normally that is not required, but it could be a good idea if used differently by different people. You may let the internal API extend the public.
I do not like the 'impl' or 'support' names, but they help separate the less important stuff from the important (domain and API). When it comes to naming, I like to be as concrete as possible. If you have a package called 'utils' with 20 classes, move StringUtils to support/string, HttpUtil to support/http and so on.

Are there best practices with regards to the organisation of packages in Java and what goes in them?
Not really, no. There are lots of ideas, and lots opinions, but real "best practice" is to use your common sense!
(Please read No best Practices for a perspective on "best practices" and the people who promote them.)
However, there is one principle that probably has broad acceptance. Your package structure should reflect your application's (informal) module structure, and you should aim to minimize (or ideally entirely avoid) any cyclic dependencies between modules.
(Cyclic dependencies between classes in a package / module are just fine, but inter-package cycles tend to make it hard understand your application's architecture, and can be a barrier to code reuse. In particular, if you use Maven you will find that cyclic inter-package / inter-module dependencies mean that the whole interconnected mess has to be one Maven artifact.)
I should also add that there is one widely accepted best practice for package names. And that is that your package names should start with your organization's domain name in reverse order. If you follow this rule, you reduce the likelihood of problems caused by your (full) class names clashing with other peoples'.

I've seen some people promote 'package by feature' over 'package by layer', but I've used quite a few approaches over many years and found 'package by layer' much better than 'package by feature'.
Further to that, I have found that a hybrid: the 'package by module, layer then feature' strategy works extremely well in practice as it has many advantages of 'package by feature':
Promotes creation of reusable frameworks (libraries with both model
and UI aspects)
Allows plug and play layer implementations - virtually impossible with 'package by feature', because it places layer implementations in the same package/directory as the model code.
Many more...
I explain in depth here: Java Package Name Structure and Organization, but my standard package structure is:
revdomain.moduleType.moduleName.layer.[layerImpl].feature.subfeatureN.subfeatureN+1...
Where:
revdomain Reverse domain, e.g., com.mycompany
moduleType [app*|framework|util]
moduleName, e.g., myAppName if module type is an app or 'finance' if it’s an accounting framework
layer [model|ui|persistence|security etc.,]
layerImpl, e.g., wicket, jsp, jpa, jdo, hibernate (Note: not used if layer is model)
feature, e.g., finance
subfeatureN, e.g., accounting
subfeatureN+1, e.g., depreciation
*Sometimes 'app' is left out if moduleType is an application, but putting it in there makes the package structure consistent across all module types.

I'm not aware of standard practices for package organization. I generally create packages that cover some reasonably broad spectrum, but I can differentiate within a project. For example, a personal project I'm currently working on has a package devoted to my customized UI controls (full of classes subclassing swing classes). I've got a package devoted to my database management stuff, I've got a package for a set of listeners/events that I've created, and so on.
On the other hand I've had a coworker create a new package for almost everything he did. Each different MVC he wanted got its own package, and it seemed a MVC set was the only grouping of classes allowed to be in the same package. I recall at one point he had 5 different packages that each had a single class in them. I think his method is a little bit on the extreme (and the team forced him to reduce his package count when we simply couldn't handle it), but for a nontrivial application, so would putting everything in the same package. It's a balance point you and your teammates have to find for yourself.
One thing you can do is try to step back and think: if you were a new member introduced to the project, or your project was released as open source or an API, how easy/difficult would it be to find what you want? Because for me, that's what I really want out of packages: organization. Similar to how I store files in folder on my computer, I expect to be able to find them again without having to search my entire drive. I expect to be able to find the class I want without having to search the list of all classes in the package.

Java package politics

I always doubt when creating packages, I want to take advantage of the package limited access but at the same time I want to have similar classes divided into packages.
The problem comes when you understand that packages are not hierarchical in Java:
At first, packages appear to be
hierarchical, but they are not.
source
Imagine I have an API defined with its classes at foo.bar, only the classes the API client needs are set public. Then I have another package with some internal objects I need in the API defined at foo.bar.pojos, this classes need to be public so they can be accessed by foo.bar but this means the API client could also access them if the package foo.bar.pojos is imported.
What is the common package politic that should be followed?

I've seen two ways of doing.
The first one consists in separating the public API and internal classes into two different artefacts (jars). The documentation is separated as well, and it's thus easy for the end user to make the distinction between what is internal and what is not. But it sometimes make things more complex to have two jars, two source trees, etc.
The second one consists in delivering a single jar, but have a good documentation allowing to know what's internal and what's not. The textual documentation can explain how to use the API (and thus avoids talking about the internals). And the javadoc can specify that a class is for internal use and is thus subject to changes.

Yes, Java packages don't give you enough control over your dependencies. The classic way to deal with this is to put external APIs in one package and internal implementation classes in another, and rely on people's good sense to avoid creating dependencies on the latter.
With Maven and OSGI, you have an additional mechanism for managing dependencies between modules / bundles of packages. In the case of OSGI, you can explicitly declare some packages as not exported, and an OSGI aware development environment will prevent people creating harmful dependencies. Maven's module support is weaker, but at least it controls dependency cycles.
Finally, you could use custom PMD rules to enforce your project's modularization conventions ... in the same way that there are rules to discourage dependencies on Java's "com.sun.*" package tree.

It is a mess.
Using only what Java itself offers, you have to put everything in the same package. You end up with a single (or a few) packages with lots of classes, and no good way to group them for yourself (but at least that problem does not leak outside). Most people don't do that, though, and as a result, your (as a developer on top of these libraries) public classpath is littered with stuff you should never need to see.
You might like OSGi, which has (and enforces) the concept of bundle-private packages. Those are not exported to the outside world.

What is a good practice to combine your classes

Not to keep all my classes in a single src -> 'package_name' folder I'm creating different sub-packages in order to separate my classes by groups like - utilities, models, activities themselves, etc. I'm not sure if it is a good practice and people do the same in real projects.

Yes, it's definitely standard practice to separate your classes into packages. It's good to establish a convention for how they are separated, to make it easier to find things later. Two common approaches:
Put things into packages based on what they are: model, service, data access (DAO), etc.
Put things into packages based on what function they support (for example, java.io, java.security, etc.
I've used both and keep coming back to the former because it's less subjective (it's always clear whether a class is a model or a service, but not always clear whether it supports one function or another function).

Doing it by class type the way you describe is one way that I've seen in real projects. I don't care for it as much as I used to because when I need to make a change or add a feature I tend to need to have several packages expanded in my IDE. I prefer (when I have the choice) to group classes by feature instead. That way I know where to look for all classes that support that feature.

The convention I prefer is to group classes first by module, then by functionality. For example, you could have the following structure:
com.example.modulea - modulea specific code that doesn't have any real need of a different package
com.example.modulea.dao - data access for module a
com.example.modulea.print - printing for module a
...
com.example.moduleb - moduleb specific code that doesn't have any real need of a different package
com.example.moduleb.dao - data access for module b
com.example.moduleb.print - printing for module b
In this fashion, code is clearer by package.
In the other style, of grouping by pure functionality, the package size tends to be quite large. If your project contains 15 modules, and each module has one or more elements per package, that's at least 15 classes per package. I much prefer clearly separated packages than packages that simply group things because "oh here are some printing utilities that are used for every module but only one module actually uses one of them from this package" - it just gets confusing.

What is the purpose of defining a package in a Java file? [closed]

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 2 years ago.
Improve this question
I am a newbie and just learned that if I define say
package my.first.group.here;
...
then the Java files that are in this package will be placed under my/first/group/here directory.
What is the main purpose of putting some Java files in a package? Also, if I choose to adopt this, how should I group them?
Thank you
EDIT: For anyone who might have the same question again, I just found this tutorial on packages from Sun.

Let's start with the definition of a "Java package", as described in the Wikipedia article:
A Java package is a mechanism for
organizing Java classes into
namespaces similar to the modules of
Modula. Java packages can be stored in
compressed files called JAR files,
allowing classes to download faster as
a group rather than one at a time.
Programmers also typically use
packages to organize classes belonging
to the same category or providing
similar functionality.
So based on that, packages in Java are simply a mechanism used to organize classes and prevent class name collisions. You can name them anything you wish, but Sun has published some naming conventions that you should use when naming packages:
Packages
The prefix of a unique package name is
always written in all-lowercase ASCII
letters and should be one of the
top-level domain names, currently com,
edu, gov, mil, net, org, or one of the
English two-letter codes identifying
countries as specified in ISO Standard
3166, 1981.
Subsequent components of the package
name vary according to an
organization's own internal naming
conventions. Such conventions might
specify that certain directory name
components be division, department,
project, machine, or login names.
Examples:
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese

I a large application, you are bound to have two files named exactly the same (java.util.Date and java.sql.Date), especially when you start bringing in third party jars. So basically, you can use packages to ensure uniqueness.
Most importantly, in my opinion, packaging breaks down projects into meaningful segments. So my SQL package has sql-related code, and my logger package handles logging.

In addition to the namespacing mentioned in other answers, you can limit access to methods and fields based on the scope declared on that member.
Members with the public scope are freely accessible, to limit access you normally define them as private (i.e. hidden outside the class).
You can also use the protected scope to limit access to the type and its children.
There is also the default scope (a member with no qualifier has the default scope) which allows child types and types in the same package access to the member. This can be an effective way of sharing fields and methods without making them too widely available, and can help with testing.
For example the method below would be visible to all other members of the same package.
public class Foo {
int doSomething() {
return 1;
}
}
To test the method you could define another type in the same package (but probably a different source location), that type would be able to access the method.
public class FooTest {
#Test
int testDoSomething() {
Foo foo = new Foo();
assertEquals(1, foo.doSomething());
}
}

It allows the program to be composed from multiple different programs/components/libraries, so that their class names will not conflict and the components are easier to organize. See http://java.sun.com/docs/books/tutorial/java/package/index.html
In Java it's customary to name packages as reverse domain names. For example, if your company's domain is "initech.com" and you are making a program called "Gizmo", the package names are typically prefixed "com.initech.gizmo", with subpackages for different components of the program.

Packages are important for giving flexibility of classes separation. They can be used for:
separating projects
separating modules
separating application layers (business, web, dao)
further finer grained code separation
For example
com.mycompany.thisproject.thismodule.web
Could indicate the web layer of some module.

Ultimately, there are 3 core reasons we want to use packages in Java.
1) Easier Maintenance
Organizing classes into packages follows the separation of concerns principle by encapsulation and allows for better cohesion in the overall system design. Moving further, packaging-by-feature allows teams of developers to find relevant classes and interfaces for making changes, supporting vertical-slicing techniques for scaled approaches used in agile methodology. For more information, see blog post: Package your classes by Feature and not by Layers and Coding: Packaging by vertical slice.
2) Provide Package security
Packages allow external access to only public access modifiers on methods in contained classes. Using the protected or no modifier will only be accessible to classes within the same package. For more information, see post:
Which Java access modifier allows a member to be accessed only by the subclasses in other package?
3) Avoid similar naming
Similar to the namespaces of .NET, class names are contained within the scope of their containing package. This means that two mutually exclusive packages can contain classes with the same name. This is because the packages themselves have different names and therefore, the fully qualified names are different. For more information, see tutorial [Naming a Package: The Java Tutorials][3].

From the Wikipedia page on the topic:
"A Java package is a mechanism for organizing Java classes into namespaces similar to the modules of Modula. Java packages can be stored in compressed files called JAR files, allowing classes to download faster as a group rather than one at a time. Programmers also typically use packages to organize classes belonging to the same category or providing similar functionality."

also, if i choose to adopt this, how
should i group them?
This depends largely on the design pattern(s) you will employ in your project. For the most part (particularly, if you're quite new) you'll want to group them by functionality or some other logical similarity.

Other people have provided very Java-specific answers which are fine, but here's an analogy: why do you organize files into directories on your hard drive? Why not just have a flat file system with everything in one directory?
The answer, of course, is that packages provide organization. The part of the program that interfaces with the database is different than the part of the program that displays a UI to the user, so they'll be in different packages.
Like directories, it also provides a way to solve name conflicts. You can have a temp.txt in a couple different directories in the same way that you could have two classes that appear in different packages. This becomes important (1) when you start combining code with other people out there on the internet or (2) even realize how Java's classloading works.

Another important thing about packages is the protected member for access control.
Protected is somewhere between public (everyone can access) and private (only class internal can access). Things marked as protected can be accessed from within the same package or from subclasses. This means that for limited access you don't have to put everything in the same class.

Java is very exact in its implementation. It doesn't really leave room for fudging.
If everyone were to use the same package, they would have to find some "World Wide" way to ensure that no two class names ever collided.
This lets every single class ever written fit into its own "Place" that you don't have to look at if you don't want to.
You may have different "Point" objects defined in 4 different places on your system, but your class will only use the one you expect (because you import that one).
The way they ensure that everyone has their own space is to use your reverse domain, so mine is "tv.kress.bill". I own that domain--Actually I share it with my brother "tv.kress.doug" and even though we share the same domain, we can't have a collision.
If a hundred divisions in your company each develop in Java, they can do so without collision and knowing exactly how to divide it.
Systems that don't do this kind of division seem really flaky to me now. I might use them to hack together a script for something personal, but I'd feel uncomfortable developing anything big without some strict packaging going on.