com.google.gerrit.server.change.ChangeETagComputation Maven / Gradle / Ivy
// Copyright (C) 2019 The Android Open Source Project
//
// 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.google.gerrit.server.change;
import com.google.gerrit.entities.Change;
import com.google.gerrit.entities.Project;
import com.google.gerrit.extensions.annotations.ExtensionPoint;
/**
* Allows plugins to contribute a value to the change ETag computation.
*
* Plugins can affect the result of the get change / get change details REST endpoints by:
*
*
* - providing plugin defined attributes to {@link
* com.google.gerrit.extensions.common.ChangeInfo#plugins} (see {@link
* ChangePluginDefinedInfoFactory})
*
- implementing a {@link com.google.gerrit.server.rules.SubmitRule} which affects the
* computation of {@link com.google.gerrit.extensions.common.ChangeInfo#submittable}
*
*
* If the plugin defined part of {@link com.google.gerrit.extensions.common.ChangeInfo} depends
* on plugin specific data, callers that use the change ETags to avoid unneeded recomputations of
* ChangeInfos may see outdated plugin attributes and/or outdated submittable information, because a
* ChangeInfo is only reloaded if the change ETag changes.
*
*
By implementating this interface plugins can contribute to the change ETag computation and
* thus ensure that the ETag changes when the plugin data was changed. This way it is ensured that
* callers do not see outdated ChangeInfos.
*
* @see ChangeResource#getETag()
*/
@ExtensionPoint
public interface ChangeETagComputation {
/**
* Computes an ETag of plugin-specific data for the given change.
*
*
Note: Change ETags are computed very frequently and the computation must be
* cheap. Take good care to not perform any expensive computations when implementing this.
*
*
If an error is encountered during the ETag computation the plugin can indicate this by
* throwing any RuntimeException. In this case no value will be included in the change ETag
* computation. This means if the error is transient, the ETag will differ when the computation
* succeeds on a follow-up run.
*
* @param projectName the name of the project that contains the change
* @param changeId ID of the change for which the ETag should be computed
* @return the ETag
*/
String getETag(Project.NameKey projectName, Change.Id changeId);
}