------
 Introduction
 ------
 Dan Tran
 ------
 20014-06-10
 ------


 ~~ NOTE: For help with the syntax of this file, see:
 ~~ http://maven.apache.org/doxia/references/apt-format.html


Introduction

    {{{https://swarm.workshop.perforce.com/files/guest/perforce_software/p4maven/main}P4Maven}} is a
    {{{http://maven.apache.org/scm}Maven SCM}} provider using
    {{{http://www.perforce.com/perforce/doc.current/manuals/p4java-javadoc/}P4Java}} developed and open sourced
    by Perforce under BSD license in 1/2011. In 6/2014, P4Maven was refactor by Dan Tran to provide the following improvements

    * Auto discover the existing Perforce client that manages the checked out Maven source tree.
      User is no longer required to configure the client name via Java system properties.

    * Client are persisted and shared by multiple commands

    * Auto generated clients are destroyed after each JVM session (ie auto cleanup).

    * Full integration with Maven SCM and Release plugin.
      User now can release Maven project with Perforce SCM using one command ( mvn -B release:preare release:perform)

    * Comply with Maven Scm's Technology Compatibility Kit (TCK)

    * Added Lots of Maven Plugin Integration Tests.

    []

  Notes:

    * Due to large changes to the codebase, this provider and its accompany plugin have a new groupId and aritifactId -
      com.perforce.p4maven:p4maven-provider and com.perforce.p4maven:p4maven-mojo respectively.
      It also has a more comprehesive URL format.

    * This provider is not the same provider developed at Apache Maven SCM team, which uses p4 command line to interact with Perforce server.

    []



* SCM URL

	The general format for a Perforce P4Maven SCM URL is

-------
    scm:p4:[protocol:][[username[:password]@]hostname:port:]//depot/path/to/project
-------


	Examples

-------
    scm:p4://depot/path/to/project
-------

    This is best fit for mutiple sites using Perforce proxy nodes. The host and protocol properties must be configured using global configuration.

--------
    scm:p4:host://depot/path/to/project
    scm:p4:ssl:host:3666://depot/path/to/project
--------

	This is for single perforce server with no proxy.

-------
    scm:p4:ssl:user:password@host:3666://depot/path/to/project
-------

	This is for testing only due to its exposure of credentials


  Notes:

    * 'tcp' is implicitly used when protocol field is not given. See Perforce documentation to see a list of supported protocols.
       However, as of this writting P4Maven provider supports only 'tcp' and 'ssl' protocols

	[]



* Provider Global Configuration

  User can configure provide global configurations using:

    * External ${user.home}/.scm/p4maven-settings.xml

    * External environment variables

    * External Java system properties


  The XML configuration has the following format

-------------------------------
  <p4maven-settings>
    <key>value</key>
    <key>value</key>
    [...]
  </p4maven-settings>
-------------------------------

  These setttings are always overridable from command line using Java system properties (ie -Dkey=value ) if allow.
  They are overridable from system environmnet only when existing values are empty if allow.

*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| p4maven-settings Key  | ENV Key           | System Property      | Type    | Default | Description                              |
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| p4Port                | P4PORT            | P4PORT               |String   | null    | P4PORT info                              |
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| jobs                  | N/A               | P4JOBS               |String   | null    | List of Perfoce Job ID separated by space for any submit action like checkin
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| N/A                   | N/A               | P4CLIENT             |String   | null    | A client name to be used as part of A initial checkout action. Donot run with this settings when your have mulitple checkouts
|                       |                   |                      |         |         | Unpredictable result when it is set and use multitple checkouts under same JVM
|                       |                   |                      |         |         | For other action, the client name is discover or generated
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| charset               | P4CHARSET         | P4CHARSET            |String   | null    | Server connection charset
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| lockTag               | N/A               | N/A                  |boolean  | true    | Lock the created label at tag action
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| allowTagUpdate        | N/A               | N/A                  |boolean  | true    | Allow the re-used of existing tag at tag action
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| strictClientDiscovery | N/A               | N/A                  |boolean  | false   | Whether the discovered client must have its host field matches with the current host
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+
| checkStaledConnection | N/A               | N/A                  |boolean  | false   | Check for staled connection. Should turn on for session longer then login session
*-----------------------+-------------------+----------------------+---------+---------+------------------------------------------+


* Working with Maven SCM and Release Plugins

    [[]] Check out the source tree with a known client. <<Ensure the host field is set at client configuration so that P4Maven can discover the client>>

    [[]] Add this provider to plugin dependency

-----------------------------------------

  <build>
    <defaultGoal>install</defaultGoal>
    <pluginManagement>
      <plugins>
        [...]
        <!-- add this if release plugin will be used to release your project -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-release-plugin</artifactId>
          [...]
          <dependencies>
            <dependency>
              <groupId>com.perforce.p4maven</groupId>
              <artifactId>p4maven-provider</artifactId>
              <version>${p4maven.version}</version>
            </dependency>
          </dependencies>
          [...]
        </plugin>

        <!-- add this if scm plugin will be used with your project -->
        <plugin>
          <groupId>org.apache.maven.plugins</groupId>
          <artifactId>maven-scm-plugin</artifactId>
          [...]
          <dependencies>
            <dependency>
              <groupId>com.perforce.p4maven</groupId>
              <artifactId>p4maven-provider</artifactId>
              <version>${p4maven.version}</version>
            </dependencythis>
          </dependencies>
          [...]
        </plugin>
        [...]
      </plugins>
     </pluginManagement>
     [...]
   </build>

-----------------------------------------------------------------------


   [[]] Configure SCM element in your project top level pom


     * The following example show how to configure \<scm\> element with host configurations.

---------------------------------

  <scm>
    <connection>scm:p4:workshop.perforce.com:1666://guest/dantran/p4maven</connection>
    <developerConnection>scm:p4:workshop.perforce.com:1666://guest/dantran/p4maven</developerConnection>
    <url>https://swarm.workshop.perforce.com/files/guest/dantran/p4maven</url>
  </scm>

--------------------------------

     []

     * The following example show how to configure \<scm\> element without host configurations which must be set either from
       environment variable or Java system property "P4PORT".
       This configuration is suitable for multi sites, with each site has its own P4PORT mirror to a central Perforce server.

---------------------------------

  <scm>
    <connection>scm:p4://guest/dantran/p4maven</connection>
    <developerConnection>scm:p4://guest/dantran/p4maven</developerConnection>
    <url>https://swarm.workshop.perforce.com/files/guest/dantran/p4maven</url>
  </scm>

--------------------------------

    * The credential can be configured using plugin's specific properties or
      {{{http://maven.apache.org/scm/maven-scm-plugin/examples/bootstrapping-with-pom.html}local's settings.xml}}