Summary vs. Full Objects

The 2009.2 release of P4 API for Java introduced the notion of “summary” and “full” representations of objects on a P4 Server. In many cases, the P4 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 P4 Server object (such as a specific client workspace), you typically do a p4 client -o with the workspace’s name.

Similarly, P4 API for Java 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:

Copy

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 P4 Server in order to find a specific client workspace, then retrieve that client (and only that client) workspace in full.