001/**
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018
019package org.apache.hadoop.yarn.api;
020
021import java.io.IOException;
022
023import org.apache.hadoop.classification.InterfaceAudience.Public;
024import org.apache.hadoop.classification.InterfaceStability.Unstable;
025import org.apache.hadoop.yarn.api.protocolrecords.ReleaseSharedCacheResourceRequest;
026import org.apache.hadoop.yarn.api.protocolrecords.ReleaseSharedCacheResourceResponse;
027import org.apache.hadoop.yarn.api.protocolrecords.UseSharedCacheResourceRequest;
028import org.apache.hadoop.yarn.api.protocolrecords.UseSharedCacheResourceResponse;
029import org.apache.hadoop.yarn.api.records.ApplicationId;
030import org.apache.hadoop.yarn.exceptions.YarnException;
031
032/**
033 * <p>
034 * The protocol between clients and the <code>SharedCacheManager</code> to claim
035 * and release resources in the shared cache.
036 * </p>
037 */
038@Public
039@Unstable
040public interface ClientSCMProtocol {
041  /**
042   * <p>
043   * The interface used by clients to claim a resource with the
044   * <code>SharedCacheManager.</code> The client uses a checksum to identify the
045   * resource and an {@link ApplicationId} to identify which application will be
046   * using the resource.
047   * </p>
048   *
049   * <p>
050   * The <code>SharedCacheManager</code> responds with whether or not the
051   * resource exists in the cache. If the resource exists, a <code>Path</code>
052   * to the resource in the shared cache is returned. If the resource does not
053   * exist, the response is empty.
054   * </p>
055   *
056   * @param request request to claim a resource in the shared cache
057   * @return response indicating if the resource is already in the cache
058   * @throws YarnException
059   * @throws IOException
060   */
061  public UseSharedCacheResourceResponse use(
062      UseSharedCacheResourceRequest request) throws YarnException, IOException;
063
064  /**
065   * <p>
066   * The interface used by clients to release a resource with the
067   * <code>SharedCacheManager.</code> This method is called once an application
068   * is no longer using a claimed resource in the shared cache. The client uses
069   * a checksum to identify the resource and an {@link ApplicationId} to
070   * identify which application is releasing the resource.
071   * </p>
072   *
073   * <p>
074   * Note: This method is an optimization and the client is not required to call
075   * it for correctness.
076   * </p>
077   *
078   * <p>
079   * Currently the <code>SharedCacheManager</code> sends an empty response.
080   * </p>
081   *
082   * @param request request to release a resource in the shared cache
083   * @return (empty) response on releasing the resource
084   * @throws YarnException
085   * @throws IOException
086   */
087  public ReleaseSharedCacheResourceResponse release(
088      ReleaseSharedCacheResourceRequest request) throws YarnException, IOException;
089
090}