001/*
002 * Copyright 2013 Global Biodiversity Information Facility (GBIF)
003 * Licensed under the Apache License, Version 2.0 (the "License");
004 * you may not use this file except in compliance with the License.
005 * You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
010 * See the License for the specific language governing permissions and
011 * limitations under the License.
012 */
013package org.gbif.api.service.registry;
014
015import org.gbif.api.model.common.paging.Pageable;
016import org.gbif.api.model.common.paging.PagingResponse;
017import org.gbif.api.vocabulary.IdentifierType;
018
019import java.util.Collection;
020import java.util.Map;
021import java.util.UUID;
022import javax.annotation.Nullable;
023import javax.validation.constraints.NotNull;
024
025public interface NetworkEntityService<T> extends MachineTagService, TagService, CommentService, IdentifierService,
026  EndpointService, ContactService {
027
028  UUID create(@NotNull T entity);
029
030  // TODO: Define behavior when it is already deleted or does not exist
031  void delete(@NotNull UUID key);
032
033  T get(@NotNull UUID key);
034
035  /**
036   * Retrieves all titles for the requested entity keys in one go
037   */
038  Map<UUID, String> getTitles(Collection<UUID> keys);
039
040    /**
041     * Used to retrieve a list of network entities.
042     *
043     * To iterate over <em>all</em> entities you can use code like this:
044     * {@code
045     * PagingRequest req = new PagingRequest();
046     * PagingResponse<T> response;
047     * do {
048     *   response = service.list(req);
049     *   for (T obj : response.getResults()) {
050     *     doStuff();
051     *   }
052     *   req.nextPage();
053     * } while (!response.isEndOfRecords());
054     * }
055     *
056     * @return a list of network entities ordered by their creation date, newest coming first
057     */
058  PagingResponse<T> list(@Nullable Pageable page);
059
060  /**
061   * A simple search that supports paging.
062   * 
063   * @return a pageable response of network entities, with accurate counts.
064   */
065  PagingResponse<T> search(String query, @Nullable Pageable page);
066
067  /**
068   * Lists the entities by the provided identifier, scoped by type.
069   * 
070   * @return a pageable response of network entities, with accurate counts for the identifier provided
071   */
072  PagingResponse<T> listByIdentifier(IdentifierType type, String identifier, @Nullable Pageable page);
073
074  /**
075   * Lists the entities by the provided identifier, which may be of any type.
076   * 
077   * @return a pageable response of network entities, with accurate counts for the identifier provided
078   */
079  PagingResponse<T> listByIdentifier(String identifier, @Nullable Pageable page);
080
081  void update(@NotNull T entity);
082
083}