com.almworks.jira.structure.api.column.AttributeContext Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of structure-api Show documentation
Public API for the Structure Plugin for JIRA
There is a newer version: 17.25.3
package com.almworks.jira.structure.api.column;

import com.atlassian.annotations.PublicApi;
import com.atlassian.jira.user.ApplicationUser;
import com.atlassian.jira.util.I18nHelper;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.Locale;

/**
 * A {@code ColumnContext} is associated with every issue data request and Structure export request. The context
 * contains some basic information, like the current user and JIRA base URL, and it can also contain other data
 * associated with the current request by Structure or other plug-ins. The current context is passed into every call
 * to {@link com.almworks.jira.structure.api.column.data.IssueDataProvider IssueDataProvider},
 * {@link com.almworks.jira.structure.api.column.data.IssueDataField IssueDataField},
 * {@link com.almworks.jira.structure.api.column.export.ExportRendererProvider ExportRendererProvider}, and
 * {@link com.almworks.jira.structure.api.column.export.ExportRenderer ExportRenderer}.
 *
 * Please note that the context key space is shared by all plug-ins, so we advise you to use plugin-private keys
 * (e.g. singleton objects or custom enums) to avoid conflicts.
 *
 * @see ColumnContextKeys
 * @see ColumnRequestContext
 * @see ColumnRenderContext
 */
@PublicApi
public interface AttributeContext {
  /**
   * @return The logged-in user, or {@code null} if anonymous.
   */
  @Nullable
  ApplicationUser getUser();

  /**
   * @return The {@link I18nHelper} instance for the current user.
   */
  @NotNull
  I18nHelper getI18nHelper();

  /**
   * @return The current user's {@link Locale}.
   */
  @NotNull
  Locale getLocale();

  /**
   * @return The base URL of the JIRA instance.
   */
  @NotNull
  String getBaseUrl();

  /**
   * Associate an arbitrary {@code value} with the given request. The value can be retrieved by passing the same
   * {@code key} to {@link #getObject(Object)}.
   *
   * Please note that {@code ColumnContext} instances are shared by all
   * {@link com.almworks.jira.structure.api.column.data.IssueDataProvider issue data providers} or
   * {@link com.almworks.jira.structure.api.column.export.ExportRendererProvider export renderer providers} from
   * all plug-ins. Therefore we recommend you to use plugin-private keys (e.g. singleton objects or custom enums) to
   * avoid conflicts.
   *
   * @param key The key.
   * @param value The value. Pass {@code null} to clear the object associated with the given {@code key}.
   * @throws IllegalArgumentException if {@code key} is {@link ColumnContextKeys#isReadOnly(Object) read-only}.
   */
  void putObject(@NotNull Object key, @Nullable Object value);

  /**
   * Retrieve the value associated with a key.
   * @param key The key.
   * @param  The expected type of the value.
   * @return The object associated with the {@code key}, or {@code null} if none.
   * @throws ClassCastException if the value is not an instance of type {@code }.
   */
  @Nullable
   T getObject(@NotNull Object key);
}