001/*
002 * Copyright 2020 Global Biodiversity Information Facility (GBIF)
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package org.gbif.api.service.registry;
017
018import org.gbif.api.model.registry.MachineTag;
019import org.gbif.api.vocabulary.TagName;
020import org.gbif.api.vocabulary.TagNamespace;
021
022import java.util.List;
023import java.util.UUID;
024
025import javax.validation.Valid;
026import javax.validation.constraints.NotNull;
027
028/**
029 * Service provides a set of operations on {@link MachineTag}.
030 */
031@SuppressWarnings("unused")
032public interface MachineTagService {
033
034  /**
035   * Add a new {@link MachineTag} to a target entity.
036   *
037   * @param targetEntityKey key of target entity
038   * @param machineTag      tag to add
039   *
040   * @return key of tag added
041   */
042  int addMachineTag(@NotNull UUID targetEntityKey, @NotNull @Valid MachineTag machineTag);
043
044  /**
045   * Add a new {@link MachineTag} to a target entity.
046   *
047   * @param targetEntityKey key of target entity
048   * @param tagName         {@link TagName}
049   * @param value           tag value to add
050   *
051   * @return key of tag added
052   */
053  int addMachineTag(@NotNull UUID targetEntityKey, @NotNull TagName tagName, @NotNull String value);
054
055  /**
056   * Add a new {@link MachineTag} to a target entity.
057   *
058   * @param targetEntityKey key of target entity
059   * @param namespace       tag namespace
060   * @param name            name of the tag to add
061   * @param value           value of the tag to add
062   *
063   * @return key of tag added
064   */
065  int addMachineTag(@NotNull UUID targetEntityKey, @NotNull String namespace, @NotNull String name, @NotNull String value);
066
067  /**
068   * Delete an existing {@link MachineTag} from a tagged entity by tag key.
069   *
070   * @param targetEntityKey key of tagged entity
071   * @param machineTagKey   key of the tag to delete
072   */
073  void deleteMachineTag(@NotNull UUID targetEntityKey, int machineTagKey);
074
075  /**
076   * Delete machine tags from a tagged entity by tag namespace.
077   *
078   * @param targetEntityKey key of tagged entity
079   * @param tagNamespace    {@link TagNamespace}
080   */
081  void deleteMachineTags(@NotNull UUID targetEntityKey, @NotNull TagNamespace tagNamespace);
082
083  /**
084   * Delete machine tags from a tagged entity by tag namespace.
085   *
086   * @param targetEntityKey key of tagged entity
087   * @param namespace       tag namespace
088   */
089  void deleteMachineTags(@NotNull UUID targetEntityKey, @NotNull String namespace);
090
091  /**
092   * Delete machine tags from a tagged entity by tag name.
093   *
094   * @param targetEntityKey key of tagged entity
095   * @param tagName         {@link TagName}
096   */
097  void deleteMachineTags(@NotNull UUID targetEntityKey, @NotNull TagName tagName);
098
099  /**
100   * Delete machine tags from a tagged entity by namespace and tag name.
101   *
102   * @param targetEntityKey key of tagged entity
103   * @param namespace       tag namespace
104   * @param name            {@link TagName}
105   */
106  void deleteMachineTags(@NotNull UUID targetEntityKey, @NotNull String namespace, @NotNull String name);
107
108  /**
109   * List all machine tags of the entity.
110   *
111   * @param targetEntityKey key of the entity
112   *
113   * @return list of tags that belong to the entity
114   */
115  List<MachineTag> listMachineTags(@NotNull UUID targetEntityKey);
116}