P4Java Quickstart

Maven Support

P4Java is packaged with support for maven2. If you project is using maven, you can add a dependency for P4Java with the following lines:

First, add the tek42 repository to your project's pom.xml:

<repositories>
 ...
        <repository>
                <id>tek42.com</id>
                <url>http://tek42.com/maven2</url>
                <releases>
                        <enabled>true</enabled>
                        <updatePolicy>never</updatePolicy>
                </releases>
                <snapshots>
                        <enabled>true</enabled>
                </snapshots>
        </repository>
...
</repositories>

Second, add in the dependency:

<dependencies>
...
        <dependency>
                <groupId>com.tek42.perforce</groupId>
                <artifactId>p4java</artifactId>
                <version>VERSION</version>
                <scope>compile</scope>
        </dependency>
...
</dependencies>

Note: replace VERSION with whatever the current version is. Right now it is 0.7.2.

API

Here are the API basics to get you up and running fast.

Everything in p4java starts from one class, the Depot. Consider it the service in a Service Oriented Architecture. It could have easily been named PerforceService or DepotService.

Connecting

This depot "service" only needs a few configuration parameters and it can talk to you Perforce installation. The mandatory parameters are:

Port - This corresponds to P4PORT (hostname:1666).
User - This is the user to connect as.
Password - The password of the user.

The API calls to set this up are very easy...

import com.tek42.perforce.*;

Depot depot = new Depot();
depot.setPort("hostname:1666");
depot.setUser("username");
depot.setPassword("password");

// You can check to make sure the connection is good by calling:
depot.getStatus().isValid();

Retrieving the last change for a project

But now we need to actually do something. Let's try looking at what the latest change in the depot is for a specific project. For this example, we assume your depot's top level folders are all projects. Our project name is KillerApp.

import com.tek42.perforce.*;
import com.tek42.perforce.model.*;

List<Changelist> changes = depot.getChanges().getChangelists("//depot/KillerApp/..." , -1, 1);

// Or, if you know the change number, you can directly retrieve the change list.
Changelist change = depot.getChanges().getChangelist(changeNumber);

In the preceeding code, the three parameters passed to getChangeLists() refer to the path in the depot of your project, the change list to start from, and the number of change lists to return, respectively. (-1 tells the API that we don't want to specify any particular change list start point. In that case, the API uses perforce default settings and the most RECENT changelist is returned. That might seem counterintuitive, but its the way perforce works.)

Changelist details

Once you have a chnagelist, there is quite a bit of information you can look at. Here are a few examples.

// What files are affected by the last change for the project?
List<Changelist> changes = depot.getChanges().getChangelists("//depot/KillerApp/..." , -1, 1);
System.out.println("Last change included: ");
for(FileEntry file : changes.get(0).getFiles()) {
	// Here we are leveraging toString()
	System.out.println(file);
	// You could just as easily specify exactly what you need
	System.out.println(file.getAction() + " " + file.getFilename() + " " + file.getRevision());
}

// Or how about finding all jobs that were fixed in the past 10 changes?
List<Changelist> changes = depot.getChanges().getChangelists("//depot/KillerApp/..." , -1, 10);
System.out.println("Last 10 changes include jobs: ");
for(Changelist change : changes) {
	for(JobEntry job : change.getJobs()) {
		System.out.println(job);
	}
}

Working with Users

Retrieving a user is very easy. You only need the username.

User user = depot.getUsers().getUser("mwille");
System.out.println("User's full name is: " + user.getFullName());

Workspaces (a.k.a., Clientspec)

If you need to check out files from the depot, you need to get ahold of a workspace. Here is how.

Workspace workspace = depot.getWorkspaces().getWorkspace("my-workspace");
// You don't have to do this if your workspace is already setup.
workspace.setRoot("c:\\dev\\");
depot.getWorkspaces().saveWorkspace(workspace);
// Remember to always include the perforce wildcard /...
depot.getWorkspaces().syncToHead("//depot/KillerApp/...");

What about feature X??

P4Java is a work in progress. If there is something that you need but isn't yet provided by the library, there is a solution. Within the p4java.jar, we have provided the legacy Perforce API. Of course, documentation on that is light. But it is complete for most features in versions pre 2000.1. Here is how to get ahold of the legacy P4 API. Please note, you don't need to provide your depot configuration to the legacy API.

// besides the standard tek42 import, you'll also need to bring in the old api.
import com.perforce.api.*;

// An example of integrating a branch...
Branch.integrate(depot.getPerforceEnv(), "//depot/KillerApp/...", 
					"BranchName", new StringBuffer(), new Change());

For further information, download or browse the javadocs for the project.