Creating and managing projects
To develop programs in the JBuilder environment, you must first create a project.
JBuilder's integrated project management features allow you to easily create and manage projects. The AppBrowser provides the work space in which you perform most project management tasks.
This chapter explains what a project is and how to manage the projects you create in JBuilder. This chapter covers the following topics:
- What is a project?
Describes a JBuilder project, lists the types of files JBuilder automatically recognizes in a project, and explains how to display a project.
- Creating a new project
Explains how to create a project with the Project wizard and describes how to import an existing file into a project.
- Managing projects with the AppBrowser
Describes how to use the AppBrowser to manage your projects. Explains how to use the project tree, the Opened Files list, and the directory tree for project management.
- Opening projects
Explains how to open projects.
- Working with files
Discusses file management tasks, such as creating files, adding and removing files and classes to and from projects, opening files outside of projects, and adding packages to projects.
- Working with multiple projects
Describes how to manage more than one project at a time.
- Where are my files?
Explains where JBuilder finds the files it needs as you drill down into source code, compile your programs, and run and debug your programs.
- Packages
Explains packages and describes package names and naming conventions. Introduces Borland packages.
What is a project?
In its simplest form, a project is just a holder of files. Generally, a project is used to "hold" the files that together make up a JBuilder application or applet. These files can be in any directory. The project ties them all together.
The information about each JBuilder project is stored in a project file that has a .jpr file extension. This project file contains a list of all the files in the project and the project settings and properties. JBuilder uses the information in the project file when you load, save, or build a project and sometimes when you use a wizard. You don't edit a project file directly, but it is modified whenever you use the JBuilder development environment to add and remove files and set project options. You can see the project file as a node at the top of the project tree in the Navigation pane of the AppBrowser.
While you can include any type of file in a JBuilder project, these are the types of files that JBuilder automatically recognizes and has an appropriate view for.
File types in a JBuilder project
|
File types |
Description |
|
.jpr |
JBuilder project file. |
.java |
Java source file. |
.class |
Compiled class file. There is one for each class in a .java source file. |
.gif |
Graphics file. |
.jpg |
Graphics file. |
.bmp |
Graphics file. |
.au |
Sound file. |
.wav |
Sound file. |
.html |
HTML document. |
|
See also:
Where are my files?
Displaying a project
JBuilder displays each project within its own AppBrowser. Therefore, if you have more than one project open, JBuilder opens an AppBrowser for each.
The following figure shows a new project file with a .jpr extension. The project contains two source files. These files are represented as nodes in the project tree.
Creating a new project
JBuilder gives you several ways for starting a new project. The method you choose to begin a project depends on what your intended goal is for the project.
You might want to start a new project by creating only the project file and adding files later. Or if you intend to design an application or applet, you can use one of JBuilder's wizards to automatically generate the framework for your application or applet. The wizard automatically generates a project file and imports the basic files if no other project is already open.
Creating a new project with the Project wizard
JBuilder provides the Project wizard to assist in creating a new project. The Project wizard automatically sets up the framework for the project and gives you the opportunity to enter informative data about the project such as its location on disk, the author of the project, and a description.
The Application and Applet wizards both have a shortcut to the Project wizard. If either one of those wizards is launched when a project is not open, the Project wizard will be launched first and a new project created. Then, control returns to the wizard that was first invoked. The new application or applet will automatically be added to the newly created project. Of course, the Application and Applet wizards can be run at any time during the development of a project and the appropriate files will be added to the project.
To create a new project with the Project wizard,
- Choose File|New Project..
The Project wizard is displayed.
- Enter the name of the project file. Make sure the file extension is .jpr.
- Fill in the title, author, company, and description fields. These fields are optional.
- Click Finish when you're done.
The new project is dipslayed in its own AppBrowser.
Creating a new project without using the Project wizard
To create a project without using the Project wizard,
- Choose File|Open/Create.
The Open/Create dialog box appears.
- Select the File tab, set the file type to Java Projects, and enter a file name (make sure it has the extension .jpr).
- Choose OK.
A new AppBrowser appears with the project node visible in the Navigation pane.
Importing an existing file
To import an existing file into the newly created project,
- Choose the Add to Project button
at the top of the Navigation pane.
The Open/Create dialog box appears.
- Select the File tab and set the file type to match the file you wish to import.
- Navigate to the directory that contains the file to be imported.
- Highlight the file.
- Choose Open.
Managing projects with the AppBrowser
The AppBrowser enables you to perform project management tasks such as the following:
- See all files in a project.
- Open and edit files.
- Add source files and packages to a project.
- Navigate through directories.
- Drag and drop files from a directory into a project.
- Browse HTML files and Web graphics.
- Maintain a convenient list of opened and edited files.
- Drill down into the structure of classes, methods, and code elements.
The AppBrowser shows a project tree, Opened Files list, or directory tree in the Navigation pane, depending on which tab is selected at the bottom of the window. These trees enable you to navigate through a hierarchy or list of files and select a file.
When you select a file in any of the tree views, the file is presented in the relevant panes of the AppBrowser: the Source pane (for editing), the View pane (for HTML browsing), and the Structure pane (for navigating through methods or HTML headings). When you select a Web graphic file, JBuilder displays the image in the Viewer pane.
See also:
Using the AppBrowser
Using the project tree to manage projects
The project tree enables you to select a file in the current project. The project tree shows only the files and packages that are included in the project. The location of a file in the project tree does not necessarily match the placement of the file in a directory. A node of the project tree can be a file or package.
You can drag-and-drop a file from the Directory browser or from the Windows Explorer onto the Opened tab to add the file to the Opened Files list without adding it to the project.
Using the Opened Files list in project management
The Opened Files list keeps track of all the files you opened or edited. These files do not have to be a part of your current project. The list of opened and edited files can contain files that you want access to while working on a project. It provides a convenient, termporary workspace in which to gather files that might be spread across several directories.
For example, if you want to modify the source code of an independent package in another directory, you can put the package file in the Opened Files list so you can have easy access to it. If you later decide to add the package to the current project, you can drag the package icon from the Opened Files list onto the Project tab.
The Opened Files list, like the project and directory trees, enables you to select various types of files that then appear in the panes relevant to that file type.
To view the Opened Files list, click the Opened tab. The list appears in the Navigation pane.
The Opened Files list is created automatically when you open or edit files. You can also drag and drop files from the directory or project tree onto the Opened tab; these are added to the list of files even if they haven't been opened yet.
Using the directory tree to manage projects
The directory tree enables you to
- View and navigate through local and network directories.
- Open files in any directory.
- View HTML files in the Content pane.
- Choose text files and see their content in the Content pane.
- Open files whose content you wish to edit in the Content pane.
- Drag and drop files from any directory to a project or Opened Files list.
To display the directory tree,
- Choose the Directory tab, located at the bottom of the Structure pane.
- The directory tree appears in the Navigation pane.
The directory tree provides an easy way for you to find and add files to your JBuilder projects.
To add a file to a JBuilder project using the directory tree,
- Choose the Directory tab.
- Navigate to the directory you want and locate the file you want to add to your project.
- Select the file and drag and drop it onto the Project tab.
To add a file to the Opened Files list using the directory tree,
- Choose the Directory tab.
- Navigate to the directory you want and locate the file you want to add to the list of opened files.
- Select the file and drag and drop it onto the Opened tab.
Opening projects
There are two ways to open a project. You can either use the File|Open/Create dialog box or the directory tree.
To open a project using the File|Open/Create dialog box,
- Choose File|Open/Create to display the File Open/Create dialog box.
- In the Files of Type box, select Java Projects to display only JBuilder project files.
- Select the .jpr file you want to open.
- Choose Open.
To open a project using the directory tree,
- Choose the Directory tab.
The directory tree appears in the AppBrowser.
- In the directory tree, double-click the directories or click the navigation buttons above the directory tree to navigate through the directories until you reach the directory that holds the project you want to open.
- Double-click the project file.
An AppBrowser appears, displaying the new project node in the project tree. If you have opened more than one project, each project appears in its own AppBrowser.
Working with files
This section describes how to work with files within a JBuilder project. These are the topics:
Creating a new file
JBuilder enables you to create files and add them to an open project in a single step. Or you can create a new file, save it to a directory, and use it later.
To create a new file,
- Choose File|Open/Create or click the Add To Project button
at the top of the Navigation pane.
The File Open/Create dialog appears.
- If you want to immediately add the file to the current project, check the Add To Project check box. If you want to save the file to a directory, select a directory from the drop-down list.
- Name the file.
- Choose Open.
The file is created, and a node for the file appears in the project tree if you checked the Add To Project check box.
To add text to the file, click the file node and enter text in the Source pane.
If you do not already have an AppBrowser open when you create a file, an AppBrowser appears, showing the new file in the project tree. The Source pane is blank. You can type text in the Source pane such as the code for a new class.
After you edit a file, save it by using File|Save or pressing Ctrl+S. The path and directory in which the file is saved appears on the status bar at the top of the AppBrowser.
Adding existing files to a project
You can add an existing file to a project by dragging and dropping it or by using the File Open/Create dialog box.
To add a file using drag and drop,
- Click the Directory tab.
- Locate the file you want to add to the project using the Directory tree.
- Drag the file from the Directory tree and drop it onto the Project tab.
You can also locate files using the Windows Explorer and drag and drop them onto the Project tab.
To drag and drop files from one AppBrowser to another,
- Select the file you want to add within another project's AppBrowser.
- Drop the file on the Opened tab or tree, or onto the Project tab or tree of another AppBrowser.
To add a file using the File Open/Create dialog box,
- Choose File|Open/Create or choose the Add to Project button
at the top of the Navigation pane.
The File Open/Create dialog box is displayed.
- Select a file or specify a new file name in the dialog box.
- Check the Add To Project check box.
- Choose Open.
The file is added to the project tree. If you don't check the Add To Project check box, the file is not added to the project, but is added to the list of opened files instead.
Adding a Java class to a project
To add a Java class to a project,
- Choose File|Open/Create or choose the Add to Project button
at the top of the Navigation pane.
The File Open/Create dialog box is displayed.
- Choose the Packages tab.
- Choose the Class (Fully Qualified Name) option.
- Navigate to the desired class file.
- Choose OK.
The class is added to the Project tree. If you don't check the Add to Project check box, the class file is not added to the project, but is added to the list of opened files.
Adding a package to a project
To add, or import, a package to a project,
- Choose File|Project Properties.
The Project page of the Properties dialog box appears.
- In the Source Path box, enter the directory for the package to add and choose OK.
- Choose File|Open/Create or click the Add to Project button
at the top of the Navigation pane.
The File Open/Create dialog box is displayed.
- Choose the Packages tab.
- Choose the Package option.
The list of available packages appears, including packages in the directory you added to the source path.
- Select the package to add.
- Check the Add to Project check box.
- Choose OK.
Removing a file from a project
To remove a file from a project,
- Click the Project tab in the AppBrowser, and select the file in the project tree.
- Click the Remove From Project button
at the top of the Navigation pane or choose File|Remove From Project.
The file is now deleted from the project and is removed from the project tree.
Opening a file outside of a project
Occasionally you might want to open a file, but you don't want to add it to a project. You can use the File|Open/Create command or you can find the file want to open in the directory tree and double-click it.
To open a file without adding it to a project,
- Choose File|Open/Create.
- Select the file you want to open.
- Leave the Add to Project check box unchecked.
- Choose Open.
The file is added to the Opened Files list and is displayed in the Content pane of the AppBrowser. If the file is a text file, the Source tab is selected and you can edit the file. If the file is a graphics file, the Viewer tab is selected and you can view the file but not edit it.
Working with multiple projects
You can work on multiple projects simultaneously in the JBuilder development environment. Each project appears in its own AppBrowser.
This section describes how to work with multiple projects. These are the covered topics:
Switching between projects
To switch between projects, click on the Project browser (the AppBrowser with the Project tab selected) for the project you want to switch to.
Editing a file in another project that is closed
When you have one AppBrowser open, you can modify files in another project without opening that project.
To modify a file in another project that is closed,
- Select the Directory tab at the bottom of the AppBrowser.
- Navigate to the directory containing the file you want to modify and double-click the file.
The source code for the file appears in the Source pane.
- Edit the code and save your changes.
- Look at the status bar at the top of the AppBrowser window to see the project and filename.
- Select the Project tab to return to the current, open project.
Saving multiple projects
To save changes to all open files and projects, choose File|Save All.
Closing multiple projects
To close all open files and projects, choose File|Close All.
Where are my files?
Each file in a project is stored with a relative path to the location of the .jpr file, or an explicit path if necessary. JBuilder uses the source, class, and out paths to find and save files. The source directory contains source files, the class directory contains .class files used in your project, and the out path contains the .class files that are the result of compiling files in your project.
To display the path settings, choose File|Project Properties, and select the Project tab. When you change path settings, you can include relative paths. If you include multiple directories, separate them with semicolons. For example,
..\lib\jbcl.zip;..lib\lib\jgl.zip;..\java\lib\classes.zip;..\classes;..\java\classes
Note that this path includes .zip files. If the classes you want are grouped in a .zip file, you must include the name of the .zip file as well as the directory it is found in.
How JBuilder finds files when you drill down
When you drill down to explore source code, JBuilder searches for the .java files using the source path. By default, the src.zip file is included in the source path. src.zip holds the Java libraries and is used when your explorations lead you into the Java libraries source code.
For more information about drilling down, see Drilling down into other classes and interfaces.
How JBuilder finds files when you compile
When you compile your project, JBuilder uses all three path settings. It compares the .class files in the class path with their source files and determines if the .class files need to be recompiled to bring them up to date. The resulting .class files from your source code are placed in the specified out path.
For more information about compiling files, see Compiling Java programs.
How JBuilder finds class files when you run or debug
When you run your program, JBuilder uses the out path to find classes your source code created, and it uses the class path to locate other classes your program uses. When you debug your program, it uses the source path to find files as you step through code.
Packages
Java provides a way to group together .java and .class files into a package. All the files that make up the source for a Java package are in the same directory; all compiled files are in another directory. Usually the files in a package are related, so a package is much like a library of either source files (.java files) or classes (.class files). The name of the package always matches some portion of the far end of the directory name in which the .class or .java files are found.
As you create your programs, you will want to create your own packages to hold related classes. For example, you might have a set of classes for drawing figures and within them some classes related to creating animal figures. The individual classes could include a Dog.class, Cat.class, Horse.class and so on. You could group all of the figure classes together in a figure package and further group the animals in a figure.animal package. Since a package always refers to a directory, the animal figure files would be stored in a directory path where the last two directories were figure\animal.
Source Path + Package Path = .java file location
It is important to understand what pieces of information JBuilder uses to build the directory location for any given .java file. The first part of the directory path is determined by the Source Path. The Source Path is the "root" from which JBuilder will add package paths to create the directory structure for the .java files used in your Java projects. Source Path is defined at the project level and can been modified by choosing File|Project Properties.
The second part of the directory path is determined by the package name. On a directory level, the package name is just the rest of the path after the Source Path up to the source file name. For example, if the Source Path was c:\JBuilder\myprojects, the package name for the file c:\JBuilder\myprojects\figure\animal\Cat.java would be figure.animal.
Don't let the periods and backslashes confuse you. When you talk about packages, you use periods to separate the parts of a package. Use backslashes to get the directory path for the package.
Out Path + Package Path = .class file location
The directory location for the .class file is determined by the Out Path and the package name. The Out Path is the "root" from which JBuilder will add package paths to create the directory structure for the .class files generated by the compiler. Out Path is defined at the project level and can be modified by choosing File|Project Properties.
The second part of the directory path is determined by the package name. Continuing with the example above, if Out Path is c:\JBuilder\myClasses, the compiled .class file for Cat.java in the package figure.animal would be placed in c:\JBuilder\myClasses\figure\animal\Cat.class.
Package Naming Convention
The following package naming conventions are recommended for use in all Java Programs. However, where reason dictates otherwise, the convention should be modified as appropriate. Of course, by using the outlined conventions you will avoid naming conflicts that may arise.
Package names should start with an Internet domain name, only reversed. For example, if you were using the domain name myDomain.COM, your package names should be prefixed with COM.myDomain. The first component of a unique package name should always be written in all-uppercase ASCII letters and should be on of the top-level domain names (for example, COM, EDU, GOV, MIL, NET, ORG). While Windows is not case sensitive other platforms are. Be particularly careful about case sensitivity when naming and referring to packages.
This convention allows for unique package name by starting off with a well established naming registry instead of creating a new one. The Java compiler does not enforce this convention and it may be unnecessary overhead for packages that are going to stay local.
Additional conventions have been recommended in order to encourage consistency in readability and maintainability. These include:
- Package names should be one word (for example, figure, animal, model).
- Package names should be singular (for example, figure vs. figures and animal vs. animals).
- Package names should be all lower case (for example, figure vs. Figure and figure vs. FIGURE).
- If a package name must be more than one word, it should still be all lower case (for example, fourwordpackagename vs. FourWordPackageName).
Using packages in JBuilder
When using classes from another package, your code will often use an import statement such as
import figure.animal.*;
You seldom need to enter an import statement directly into your source code, as JBuilder's designers and wizards can add these statements for you automatically. Also, it isn't essential to import packages. You can reference a particular class in your code by fully qualifying the name of the class (that is: package name + class name without the extension). For example:
On the other hand, if the import statement above (import figure.animal.*
) was included in your source code, the reference to the Cat class would be just Cat instead of figure.animal.Cat. Importing packages isn't essential, but it is a convenient shortcut because it allows you to omit the package name when your code references a particular class.
There is much more to learn about packages that is beyond the scope of this discussion. Refer to one of the many excellent third-party sources for more infomration about packages and the Java language.