com.netflix.genie.web.agent.services.AgentJobService Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of genie-web Show documentation
genie-web
There is a newer version: 4.3.20
/*
 *
 *  Copyright 2018 Netflix, Inc.
 *
 *     Licensed under the Apache License, Version 2.0 (the "License");
 *     you may not use this file except in compliance with the License.
 *     You may obtain a copy of the License at
 *
 *         http://www.apache.org/licenses/LICENSE-2.0
 *
 *     Unless required by applicable law or agreed to in writing, software
 *     distributed under the License is distributed on an "AS IS" BASIS,
 *     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *     See the License for the specific language governing permissions and
 *     limitations under the License.
 *
 */
package com.netflix.genie.web.agent.services;

import com.netflix.genie.common.internal.dtos.AgentClientMetadata;
import com.netflix.genie.common.internal.dtos.ArchiveStatus;
import com.netflix.genie.common.internal.dtos.JobRequest;
import com.netflix.genie.common.internal.dtos.JobSpecification;
import com.netflix.genie.common.internal.dtos.JobStatus;
import com.netflix.genie.common.internal.exceptions.checked.GenieJobResolutionException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieAgentRejectedException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieIdAlreadyExistsException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieInvalidStatusException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieJobAlreadyClaimedException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieJobNotFoundException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieJobResolutionRuntimeException;
import com.netflix.genie.common.internal.exceptions.unchecked.GenieJobSpecificationNotFoundException;
import org.springframework.validation.annotation.Validated;

import javax.annotation.Nullable;
import javax.validation.ConstraintViolationException;
import javax.validation.Valid;
import javax.validation.constraints.NotBlank;
import java.util.Map;

/**
 * A Service to collect the logic for implementing calls from the Agent when a job is launched via the CLI.
 *
 * @author tgianos
 * @since 4.0.0
 */
@Validated
public interface AgentJobService {

    /**
     * Shake hands and allow a client or reject it based on the supplied {@link AgentClientMetadata}.
     *
     * @param agentMetadata The metadata about the agent starting to run a given job
     * @throws GenieAgentRejectedException  If the server rejects the client based on its metadata
     * @throws ConstraintViolationException If the arguments fail validation
     */
    void handshake(@Valid AgentClientMetadata agentMetadata);

    /**
     * Provide configuration properties for an agent that is beginning to execute a job.
     *
     * @param agentMetadata The metadata about the agent starting to run a given job
     * @return a map of properties for the agent
     * @throws ConstraintViolationException If the arguments fail validation
     */
    Map getAgentProperties(@Valid AgentClientMetadata agentMetadata);

    /**
     * Reserve a job id and persist job details in the database based on the supplied {@link JobRequest}.
     *
     * @param jobRequest          The job request containing all the metadata needed to reserve a job id
     * @param agentClientMetadata The metadata about the agent driving this job request
     * @return The unique id of the job which was saved in the database
     * @throws GenieIdAlreadyExistsException If the id requested along with the job request is already in use
     * @throws ConstraintViolationException  If the arguments fail validation
     */
    String reserveJobId(@Valid JobRequest jobRequest, @Valid AgentClientMetadata agentClientMetadata);

    /**
     * Resolve the job specification for job identified by the given id. This method will persist the job specification
     * details to the database.
     *
     * @param id The id of the job to resolve the specification for. Must already have a reserved an id in the database
     * @return The job specification if one could be resolved
     * @throws GenieJobResolutionException        On error resolving the job given the input parameters and system state
     * @throws ConstraintViolationException       If the arguments fail validation
     * @throws GenieJobResolutionRuntimeException If job resolution fails due to a runtime error (as opposed to
     *                                            unsatisfiable constraints)
     */
    JobSpecification resolveJobSpecification(
        @NotBlank String id
    ) throws GenieJobResolutionException, GenieJobResolutionRuntimeException;

    /**
     * Get a job specification if has been resolved.
     *
     * @param id the id of the job to retrieve the specification for
     * @return The job specification for the job
     * @throws GenieJobNotFoundException              If the job has not yet had its ID reserved and/or can't be found
     * @throws GenieJobSpecificationNotFoundException If the job exists but the specification hasn't been
     *                                                resolved or saved yet
     * @throws ConstraintViolationException           If the arguments fail validation
     */
    JobSpecification getJobSpecification(@NotBlank String id);

    /**
     * Run the job specification resolution algorithm on the given input but save nothing in the system.
     *
     * @param jobRequest The job request containing all the metadata needed to resolve a job specification
     * @return The job specification that would have been resolved for the given input
     * @throws GenieJobResolutionException  On error resolving the job given the input parameters and system state
     * @throws ConstraintViolationException If the arguments fail validation
     */
    JobSpecification dryRunJobSpecificationResolution(@Valid JobRequest jobRequest) throws GenieJobResolutionException;

    /**
     * Set a job identified by {@code id} to be owned by the agent identified by {@code agentClientMetadata}. The
     * job status in the system will be set to {@link com.netflix.genie.common.dto.JobStatus#CLAIMED}
     *
     * @param id                  The id of the job to claim. Must exist in the system.
     * @param agentClientMetadata The metadata about the client claiming the job
     * @throws GenieJobNotFoundException       if no job with the given {@code id} exists
     * @throws GenieJobAlreadyClaimedException if the job with the given {@code id} already has been claimed
     * @throws GenieInvalidStatusException     if the current job status is not
     *                                         {@link com.netflix.genie.common.dto.JobStatus#RESOLVED}
     * @throws ConstraintViolationException    If the arguments fail validation
     */
    void claimJob(@NotBlank String id, @Valid AgentClientMetadata agentClientMetadata);

    /**
     * Update the status of the job identified with {@code id} to be {@code newStatus} provided that the current status
     * of the job matches {@code newStatus}. Optionally a status message can be provided to provide more details to
     * users. If the {@code newStatus} is {@link JobStatus#RUNNING} the start time will be set. If the {@code newStatus}
     * is a member of {@link JobStatus#getFinishedStatuses()} and the job had a started time set the finished time of
     * the job will be set.
     *
     * @param id               The id of the job to update status for. Must exist in the system.
     * @param currentStatus    The status the caller to this API thinks the job currently has
     * @param newStatus        The new status the caller would like to update the status to
     * @param newStatusMessage An optional status message to associate with this change
     * @throws GenieJobNotFoundException    if no job with the given {@code id} exists
     * @throws GenieInvalidStatusException  if the current status of the job identified by {@code id} in the system
     *                                      doesn't match the supplied {@code currentStatus}.
     *                                      Also if the {@code currentStatus} equals the {@code newStatus}.
     * @throws ConstraintViolationException If the arguments fail validation
     */
    void updateJobStatus(
        @NotBlank String id,
        JobStatus currentStatus,
        JobStatus newStatus,
        @Nullable String newStatusMessage
    );

    /**
     * Retrieve the status of the job identified with {@code id}.
     *
     * @param id The id of the job to look up.
     * @return the current status of the job, as seen by this node
     * @throws GenieJobNotFoundException    if no job with the given {@code id} exists
     * @throws ConstraintViolationException If the arguments fail validation
     */
    JobStatus getJobStatus(@NotBlank String id);

    /**
     * Update the archive status status of the job identified with {@code id} to be {@code newStatus}.
     * Notice this is a 'blind write', the currently persisted value will always be overwritten.
     *
     * @param id               The id of the job to update status for. Must exist in the system.
     * @param newArchiveStatus The new archive status the caller would like to update the status to
     * @throws GenieJobNotFoundException    if no job with the given {@code id} exists
     * @throws ConstraintViolationException If the arguments fail validation
     */
    void updateJobArchiveStatus(
        @NotBlank String id,
        ArchiveStatus newArchiveStatus
    );
}