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.common.paging.Pageable;
019import org.gbif.api.model.common.paging.PagingResponse;
020import org.gbif.api.vocabulary.IdentifierType;
021
022import java.util.Collection;
023import java.util.Map;
024import java.util.UUID;
025
026import javax.annotation.Nullable;
027import javax.validation.Valid;
028import javax.validation.constraints.NotNull;
029
030@SuppressWarnings("unused")
031public interface NetworkEntityService<T>
032    extends MachineTagService,
033        TagService,
034        CommentService,
035        IdentifierService,
036        EndpointService,
037        ContactService {
038
039  /**
040   * Creates a new entity. Data should be valid.
041   *
042   * @param entity to create
043   * @return a key of the newly created entity.
044   */
045  UUID create(@NotNull @Valid T entity);
046
047  /**
048   * Updates an existing entity. Data should be valid.
049   *
050   * @param entity to update.
051   */
052  void update(@NotNull @Valid T entity);
053
054  // TODO: Define behavior when it is already deleted or does not exist
055
056  /**
057   * Deletes an entity by the provided key.
058   *
059   * @param key of the entity to delete.
060   */
061  void delete(@NotNull UUID key);
062
063  /**
064   * Gets an entity by the provided key.
065   *
066   * @param key of the entity to get
067   * @return an entity.
068   */
069  T get(@NotNull UUID key);
070
071  /**
072   * Retrieves all titles for the requested entity keys in one go
073   *
074   * @param keys entity keys to get titles
075   * @return pairs of entity key - entity title.
076   */
077  Map<UUID, String> getTitles(@NotNull Collection<UUID> keys);
078
079  /**
080   * Used to retrieve a list of network entities.
081   *
082   * <p>To iterate over <em>all</em> entities you can use code like this: {@code PagingRequest req =
083   * new PagingRequest(); PagingResponse<T> response; do { response = service.list(req); for (T obj
084   * : response.getResults()) { doStuff(); } req.nextPage(); } while (!response.isEndOfRecords()); }
085   *
086   * @return a list of network entities ordered by their creation date, newest coming first
087   *     <p>Deprecated: use the list with parameters service.
088   */
089  @Deprecated
090  PagingResponse<T> list(@Nullable Pageable page);
091
092  /**
093   * A simple search that supports paging.
094   *
095   * @return a pageable response of network entities, with accurate counts.
096   *     <p>Deprecated: use the list with parameters service.
097   */
098  @Deprecated
099  PagingResponse<T> search(String query, @Nullable Pageable page);
100
101  /**
102   * Lists the entities by the provided identifier, scoped by type.
103   *
104   * @return a pageable response of network entities, with accurate counts for the identifier
105   *     provided
106   *     <p>Deprecated: use the list with parameters service.
107   */
108  @Deprecated
109  PagingResponse<T> listByIdentifier(
110      IdentifierType type, String identifier, @Nullable Pageable page);
111
112  /**
113   * Lists the entities by the provided identifier, which may be of any type.
114   *
115   * @return a pageable response of network entities, with accurate counts for the identifier
116   *     provided
117   *     <p>Deprecated: use the list with parameters service.
118   */
119  @Deprecated
120  PagingResponse<T> listByIdentifier(String identifier, @Nullable Pageable page);
121
122  /**
123   * Lists the entities having a machine tag in the provided namespace, with the provided name and
124   * value.
125   *
126   * @return a pageable response of network entities, with accurate counts for the machine tag
127   *     provided
128   *     <p>Deprecated: use the list with parameters service.
129   */
130  @Deprecated
131  PagingResponse<T> listByMachineTag(
132      String namespace, @Nullable String name, @Nullable String value, @Nullable Pageable page);
133}