Package com.xebialabs.xlrelease.api.v1

## Interface PhaseApi

- All Superinterfaces:
    `ApiService`

      @Path("/api/v1/phases")
      @Consumes("application/json")
      @Produces("application/json")
      public interface PhaseApi
      extends ApiService

  Operations on phases.

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static java.lang.String` | `SERVICE_NAME` |

    - ### Fields inherited from interface com.xebialabs.xlrelease.api.ApiService

      `DEFAULT_RESULTS_PER_PAGE, DEFAULT_RESULTS_PER_PAGE_STRING, DEPTH, ORDER_BY, PAGE, PAGE_IS_OFFSET, RESULTS_PER_PAGE, ROLE_IDS_DATA`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Default Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Phase` | `addPhase​(java.lang.String releaseId, Phase phase)` | Wrapper method to add a phase to the release.
    `Phase` | `addPhase​(java.lang.String releaseId, Phase phase, java.lang.Integer position)` | Adds a phase to a release.
    `Task` | `addTask​(java.lang.String containerId, Task task, java.lang.Integer position)` | Adds a task to a phase or to a group task.
    `Phase` | `copyPhase​(java.lang.String phaseIdToCopy, int targetPosition)` | Copy a phase in a release.
    `void` | `deletePhase​(java.lang.String phaseId)` | Deletes the phase with the given ID.
    `Phase` | `getPhase​(java.lang.String phaseId)` | Returns the phase for the given identifier.
    `Phase` | `newPhase()` | Factory method to create a new instance of a phase.
    `Phase` | `newPhase​(java.lang.String title)` | Factory method to create a new instance of a Phase object.
    `java.util.List<Phase>` | `searchPhases​(java.lang.String phaseTitle, java.lang.String releaseId, PhaseVersion phaseVersion)` | Search phase within a release.
    `java.util.List<Phase>` | `searchPhasesByTitle​(java.lang.String phaseTitle, java.lang.String releaseId)` | Search phases in a release by title.
    `default java.lang.String` | `serviceName()` |
    `Phase` | `updatePhase​(Phase phase)` | Updates the properties of a phase.
    `Phase` | `updatePhase​(java.lang.String phaseId, Phase phase)` | Updates the properties of a phase.

- - ### Field Detail

    - #### SERVICE_NAME

          static final java.lang.String SERVICE_NAME

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### serviceName

          default java.lang.String serviceName()

      Specified by:
        `serviceName` in interface `ApiService`

    - #### getPhase

          @GET
          @Path("/{phaseId:.*/Phase[^/]*}")
          Phase getPhase​(@PathParam("phaseId")
                         java.lang.String phaseId)

      Returns the phase for the given identifier.
      Parameters:
        `phaseId` - the phase identifier.
      Returns:
        the phase.

    - #### updatePhase

          @PUT
          @Path("/{phaseId:.*/Phase[^/]*}")
          Phase updatePhase​(@PathParam("phaseId")
                            java.lang.String phaseId,
                            Phase phase)

      Updates the properties of a phase.
      Parameters:
        `phaseId` - the phase identifier.
        `phase` - new contents of the phase.
      Returns:
        the updated phase

    - #### updatePhase

          Phase updatePhase​(Phase phase)

      Updates the properties of a phase.
      Parameters:
        `phase` - new contents of the phase.
      Returns:
        the updated Phase

    - #### addTask

          @POST
          @Path("/{containerId:.*/Phase.*?}/tasks")
          Task addTask​(@PathParam("containerId")
                       java.lang.String containerId,
                       Task task,
                       @QueryParam("position")
                       java.lang.Integer position)

      Adds a task to a phase or to a group task. If no position is specified, then task is added to the end of the phase.
      Parameters:
        `containerId` - the phase or group task identifier
        `task` - the task to add.
        `position` - the position in the phase.task, 0-based. If left empty, then task will be added to the end of the phase.
      Returns:
        the added task

    - #### searchPhasesByTitle

          @GET
          @Path("/byTitle")
          java.util.List<Phase> searchPhasesByTitle​(@QueryParam("phaseTitle")
                                                    java.lang.String phaseTitle,
                                                    @QueryParam("releaseId")
                                                    java.lang.String releaseId)

      Search phases in a release by title.
      Parameters:
        `phaseTitle` - the phase title
        `releaseId` - the release identifier.
      Returns:
        A list of phases that match.

    - #### searchPhases

          @GET
          @Path("/search")
          java.util.List<Phase> searchPhases​(@QueryParam("phaseTitle")
                                             java.lang.String phaseTitle,
                                             @QueryParam("releaseId")
                                             java.lang.String releaseId,
                                             @QueryParam("phaseVersion")
                                             PhaseVersion phaseVersion)

      Search phase within a release.

      ReleaseId is required, all other parameters are optional. Providing the optional parameters will narrow down search.

      Parameters:
        `phaseTitle` - (part of) the phase title (optionally, if not provided, all phases are returned)
        `releaseId` - the release identifier.
        `phaseVersion` - phase version (optionally, if not provided, no filtering will be applied)
      Returns:
        A list of phases that match.

    - #### addPhase

          @POST
          @Path("/{releaseId:.*Release[^/]*}/phase")
          Phase addPhase​(@PathParam("releaseId")
                         java.lang.String releaseId,
                         Phase phase,
                         @QueryParam("position")
                         java.lang.Integer position)

      Adds a phase to a release. If no position is specified, then the phase is added as the last phase. All nested configuration items (e.g. tasks) will be removed from the provided phase.
      Parameters:
        `releaseId` - the identifier of a template/release.
        `phase` - the phase to add
        `position` - the position in the template, 0-based. If left empty, then phase will the last phase in the template
      Returns:
        add `Phase` object.

    - #### copyPhase

          @POST
          @Path("/{phaseId:.*/Phase[^/]*}/copy")
          Phase copyPhase​(@PathParam("phaseId")
                          java.lang.String phaseIdToCopy,
                          @QueryParam("targetPosition")
                          int targetPosition)

      Copy a phase in a release.
      Parameters:
        `phaseIdToCopy` - the phase id to copy
        `targetPosition` - the position where to copy the phase to within a release. Cannot be `< 0` and also not `>= release.phases.size()`
      Returns:
        copy of a `Phase` object.

    - #### addPhase

          Phase addPhase​(java.lang.String releaseId,
                         Phase phase)

      Wrapper method to add a phase to the release.
      Parameters:
        `releaseId` - the release id to add the phase to
        `phase` - the phase to add
      Returns:
        the phase object.

    - #### newPhase

          Phase newPhase()

      Factory method to create a new instance of a phase.
      Returns:
        the task object.

    - #### newPhase

          Phase newPhase​(java.lang.String title)

      Factory method to create a new instance of a Phase object.

      Example script which adds a custom phase to the current release:

           release = getCurrentRelease()
           phase = phaseApi.newPhase("My New Phase")
           phaseApi.addPhase(release.id, phase)

      Parameters:
        `title` - the title of the phase.
      Returns:
        the phase object.

    - #### deletePhase

          @DELETE
          @Path("/{phaseId:.*/Phase[^/]*}")
          void deletePhase​(@PathParam("phaseId")
                           java.lang.String phaseId)

      Deletes the phase with the given ID.
      Parameters:
        `phaseId` - the phase identifier.