001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 *     http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014package org.gbif.api.service.collections;
015
016import org.gbif.api.model.collections.CollectionEntity;
017import org.gbif.api.model.collections.MasterSourceMetadata;
018import org.gbif.api.model.common.paging.Pageable;
019import org.gbif.api.model.common.paging.PagingResponse;
020import org.gbif.api.service.registry.CommentService;
021import org.gbif.api.service.registry.IdentifierService;
022import org.gbif.api.service.registry.MachineTagService;
023import org.gbif.api.service.registry.TagService;
024import org.gbif.api.vocabulary.collections.Source;
025
026import java.util.List;
027import java.util.Optional;
028import java.util.UUID;
029
030import javax.annotation.Nullable;
031import javax.validation.Valid;
032import javax.validation.constraints.NotNull;
033
034public interface CollectionEntityService<T extends CollectionEntity>
035    extends CrudService<T>,
036        IdentifierService,
037        TagService,
038        MachineTagService,
039        CommentService,
040        ContactService,
041        OccurrenceMappingService {
042
043  /** Replaces a entity with another. The entity replaced is also deleted. */
044  void replace(UUID entityToReplaceKey, UUID replacementKey);
045
046  /**
047   * Adds {@link MasterSourceMetadata} to an entity.
048   *
049   * @param targetEntityKey key of the entity to add the metadata to
050   * @param masterSourceMetadata metadata to add
051   * @return key of the created metadata
052   */
053  int addMasterSourceMetadata(UUID targetEntityKey, MasterSourceMetadata masterSourceMetadata);
054
055  /**
056   * Removes the {@link MasterSourceMetadata} from an entity.
057   *
058   * @param targetEntityKey key of the entity whose metadata will be deleted
059   */
060  void deleteMasterSourceMetadata(UUID targetEntityKey);
061
062  /**
063   * Returns the {@link MasterSourceMetadata} of the entity.
064   *
065   * @param targetEntityKey key of the entity
066   * @return {@link MasterSourceMetadata}
067   */
068  MasterSourceMetadata getMasterSourceMetadata(@NotNull UUID targetEntityKey);
069
070  /**
071   * Finds the collection entity whose master data metadata matches with the parameters received.
072   *
073   * @param source source of the metadata
074   * @param sourceId source Id of the metadata
075   * @return {@link Optional} with the collection entity found
076   */
077  List<T> findByMasterSource(Source source, String sourceId);
078
079  /**
080   * Updates an existing entity.
081   *
082   * @param entity that will replace the existing entity.
083   * @param lockFields indicates if fields that come from an external master source has to be
084   *     locked.
085   */
086  void update(@NotNull @Valid T entity, boolean lockFields);
087}