Summary vs. Full Objects
The 2009.2 release of P4Java introduced the notion of “summary” and
“full” representations of objects on a Helix Server. In many cases, the Helix Server only returns summaries of objects that it’s been asked to list.
For example, if you issue a p4 clients
command to a
server, what comes back is a list of client metadata for known client
workspaces, but not the associated workspace views. For things like
changelists, jobs, branches, and so on, to obtain the full version of the
Helix Server
object (such as a specific client workspace), you typically do a
p4 client -o
with the workspace’s name.
Similarly, P4Java distinguishes between the summary objects returned
from the main list methods (such as IOptionsServer.getClients()
)
and the full objects returned from individual retrieval methods (such as
IOptionsServer.getClient()
).
The snippet below, edited from the ListClientDemo
sample
app, illustrates a typical usage pattern for summary and full object
retrieval:
try {
IOptionsServer server = ServerFactory.getOptionsServer("p4java://localhost:1666", null);
server.setUserName(userName);
server.login(password);
System.out.println("Clients on Perforce server at URI '"
+ serverUri + "' for user '" + userName + "':");
List<IClientSummary> clientList = server.getClients(
new GetClientsOptions().setUserName(userName));
if (clientList != null) {
for (IClientSummary clientSummary : clientList) {
// NOTE: list returns client summaries only; need to get the
// full client to get the view:
IClient client = server.getClient(clientSummary);
System.out.println(client.getName() + " "
+ client.getDescription().trim() + " "
+ client.getRoot());
ClientView clientView = client.getClientView();
if (clientView != null) {
for (IClientViewMapping viewMapping : clientView) {
System.out.println("\t\t" + viewMapping);
}
}
}
}
} catch (RequestException rexc) {
System.err.println(rexc.getDisplayString());
rexc.printStackTrace();
} catch (P4JavaException jexc) {
System.err.println(jexc.getLocalizedMessage());
jexc.printStackTrace();
} catch (URISyntaxException uexc) {
System.err.println(uexc.getLocalizedMessage());
uexc.printStackTrace();
}
Only clients owned by username are returned, and that in order to print the associated client workspace view for each retrieved summary client workspace, we get the full client object. This is more common in cases where a user might iterate across a list of all workspaces known to the Helix Server in order to find a specific client workspace, then retrieve that client (and only that client) workspace in full.