Package com.perforce.p4java.core

Class CoreFactory

java.lang.Object

com.perforce.p4java.core.CoreFactory

public class CoreFactory
extends java.lang.Object

A lightweight factory class with convenience methods for creating common P4Java objects using the default implementation classes with common default values.

Note that this is really just a useful convenience wrapper for the standard static factory methods on each core implementation class, but the point of this class is that users do not typically have to deal with implementation classes directly at all.

Each method typically includes a boolean createOnServer parameter, which, if true, tries to create the object (Client, Changelist, whatever...) on the server as well.

Since:

2011.1

Constructor Summary

Constructors

Constructor	Description
CoreFactory()

Method Summary

Modifier and Type	Method	Description
static IChangelist	createChangelist(IClient client, java.lang.String description, boolean createOnServer)	Create a new changelist object locally and optionally also create it on the server using the passed-in client for default values.
static IClient	createClient(IOptionsServer server, java.lang.String name, java.lang.String description, java.lang.String root, java.lang.String[] paths, boolean createOnServer)	Create a new client local object and optionally also create it on the server.
static IJob	createJob(IOptionsServer server, java.util.Map<java.lang.String,java.lang.Object> map, boolean createOnServer)	Simple convenience factory method to create a new local or in-server job.
static ILabel	createLabel(IOptionsServer server, java.lang.String name, java.lang.String description, java.lang.String[] mapping, boolean createOnServer)	Create a new ILabel object locally and optionally on the server.
static IUser	createUser(IOptionsServer server, java.lang.String name, java.lang.String email, java.lang.String fullName, java.lang.String password, boolean createOnServer)	Create a new IUser object locally and optionally on the server.
static IUserGroup	createUserGroup(IOptionsServer server, java.lang.String name, java.util.List<java.lang.String> users, boolean createOnServer)	Create a new user group locally and / or on the server, using "sensible" default values for non-parameters.
static IBranchSpec	newBranchSpec(IOptionsServer server, java.lang.String name, java.lang.String description, java.lang.String[] branches, boolean createOnServer)	Create a new branch spec locally and / or on the server with default values for non-parameter fields.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

CoreFactory

public CoreFactory()

Method Detail

createClient

public static IClient createClient(IOptionsServer server,
                                   java.lang.String name,
                                   java.lang.String description,
                                   java.lang.String root,
                                   java.lang.String[] paths,
                                   boolean createOnServer)
                            throws P4JavaException

Create a new client local object and optionally also create it on the server.

Only the fields corresponding to the parameters here can be explicitly set on creation; all others are given defaults that can be changed or added later. These defaults are as given for the default Client and ClientSummary constructors; exceptions include the client's user name, which is set to server.getUserName (which may cause issues later down the line if that wasn't set).

Note: users of this method are responsible for ensuring that the client you're asking to be created does not already exist -- if it does exist, this method will succeed, but the result will be an updated version of the existing client on the server, which may not be what you wanted.

Note: this does not set the server's current client to the returned value; you have to do that yourself...

Parameters:

server - non-null IOptionsServer to be associated with the client.

name - non-null client name.

description - if not null, the client description field to be used; if null, DEFAULT_DESCRIPTION will be used as a default.

root - if not null, use this as the new client's root; if null, use the server's working directory if its getWorkingDirectory method returns non-null, otherwise use the JVM's current working directory as determine by the user.dir system property.

paths - if not null, use this as the list of view map depot / client paths, in the order given, and according to the format in MapEntry.parseViewMappingString; defaults to a single entry, "//depot/... //clientname/depot/..." if not given.

createOnServer - if true, also create the client on the server; the returned client will in this case be the IClient corresponding to the on-server client (if the creation succeeded...).

Returns:

IClient

Throws:

P4JavaException - if anything went wrong during creation on the server.

createChangelist

public static IChangelist createChangelist(IClient client,
                                           java.lang.String description,
                                           boolean createOnServer)
                                    throws P4JavaException

Create a new changelist object locally and optionally also create it on the server using the passed-in client for default values.

The changelist's user field will be set to the current user; other fields and semantics are as given in the Changelist implementation class static factory methods which are called directly through this method.

Parameters:

client - non-null client to be associated with the changelist; this client object must contain a valid server field if createOnServer is true.

description - if not null, the changelist description string; if null, defaults to Changelist.DEFAULT_DESCRIPTION

createOnServer - if true, also create the client on the server.

Returns:

if createOnServer is false, the local object created; otherwise, will return the results of an IClient.createChangelist using the new local object.

Throws:

P4JavaException - if anything went wrong during object creation on the server.

createJob

public static IJob createJob(IOptionsServer server,
                             java.util.Map<java.lang.String,java.lang.Object> map,
                             boolean createOnServer)
                      throws P4JavaException

Simple convenience factory method to create a new local or in-server job.

Parameters:

server - non-null server to be associated with the job.

map - non-null job fields map.

createOnServer - if true, create the job on the server, otherwise simply return a suitably-created local job object.

Returns:

new job object.

Throws:

P4JavaException - if anything went wrong during object creation on the server.

createLabel

public static ILabel createLabel(IOptionsServer server,
                                 java.lang.String name,
                                 java.lang.String description,
                                 java.lang.String[] mapping,
                                 boolean createOnServer)
                          throws P4JavaException

Create a new ILabel object locally and optionally on the server.

Note: users of this method are responsible for ensuring that the label you're asking to be created does not already exist -- if it does exist, this method will succeed, but the result will be an updated version of the existing label on the server, which may not be what you wanted.

Parameters:

server - non-null server to be associated with this label.

name - non-null label name.

description - if not null, use this as the label's description field; if null, use Label.DEFAULT_DESCRIPTION.

mapping - if not null, use the passed-in string array as the map (in order); if null, use the single map defined in Label.DEFAULT_MAPPING.

createOnServer - if true, create the label on the server, otherwise simply return a suitably-created local label object.

Returns:

new label object

Throws:

P4JavaException - if anything went wrong during object creation on the server.

createUser

public static IUser createUser(IOptionsServer server,
                               java.lang.String name,
                               java.lang.String email,
                               java.lang.String fullName,
                               java.lang.String password,
                               boolean createOnServer)
                        throws P4JavaException

Create a new IUser object locally and optionally on the server.

Note: users of this method are responsible for ensuring that the user you're asking to be created does not already exist -- if it does exist, this method will succeed, but the result will be an updated version of the existing user on the server, which may not be what you wanted.

Note also that if createOnServer is true, user creation will fail on the server unless you have the right to create the new user -- this method uses the equivalent of 'p4 user -f' under the covers.

Parameters:

server - server to be associated with this user; must not be null if createOnServer is true.

name - non-null user name.

email - user's email address.

fullName - user's full name.

password - user's password (usually ignored).

createOnServer - if true, create the user on the server, otherwise simply return a suitably-created local user object.

Returns:

new user object; may be null if creation on server didn't work.

Throws:

P4JavaException - if anything went wrong during object creation on the server.

createUserGroup

public static IUserGroup createUserGroup(IOptionsServer server,
                                         java.lang.String name,
                                         java.util.List<java.lang.String> users,
                                         boolean createOnServer)
                                  throws P4JavaException

Create a new user group locally and / or on the server, using "sensible" default values for non-parameters.

Note: users of this method are responsible for ensuring that the user group you're asking to be created does not already exist -- if it does exist, this method will succeed, but the result will be an updated version of the existing user grup on the server, which may not be what you wanted.

Parameters:

server - server to be associated with this user group; must not be null if createOnServer is true.

name - non-null user group name.

users - possibly-null list of user group users.

createOnServer - if true, create the user group on the server, otherwise simply return a suitably-created local user group object.

Returns:

new user group object; may be null if creation on server didn't work.

Throws:

P4JavaException - if anything went wrong during object creation on the server.

newBranchSpec

public static IBranchSpec newBranchSpec(IOptionsServer server,
                                        java.lang.String name,
                                        java.lang.String description,
                                        java.lang.String[] branches,
                                        boolean createOnServer)
                                 throws P4JavaException

Create a new branch spec locally and / or on the server with default values for non-parameter fields.

Note: users of this method are responsible for ensuring that the spec you're asking to be created does not already exist -- if it does exist, this method will succeed, but the result will be an updated version of the existing branch spec on the server, which may not be what you wanted.

Parameters:

server - non-null server to be associated with the new branch spec.

name - non-null branch spec name.

description - if not null, used as the new branc spec's description field; if null, uses the BranchSpec.DEFAULT_DESCRIPTION field.

branches - if not null, use this as the list of branch spec paths, in the order given, and according to the format in MapEntry.parseViewMappingString; unlike many other core object factory methods, this one does not default if null.

createOnServer - if true, create the branch spec on the server, otherwise simply return a suitably-created local branch spec object.

Returns:

new branch spec object; may be null if server-side creation failed.

Throws:

P4JavaException - if anything went wrong during object creation on the server.