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.model.registry.Dataset;
021import org.gbif.api.model.registry.Installation;
022import org.gbif.api.model.registry.Node;
023import org.gbif.api.model.registry.Organization;
024import org.gbif.api.model.registry.search.KeyTitleResult;
025import org.gbif.api.model.registry.search.NodeRequestSearchParams;
026import org.gbif.api.vocabulary.Country;
027
028import java.util.List;
029import java.util.UUID;
030
031import javax.annotation.Nullable;
032import javax.validation.constraints.NotNull;
033
034/**
035 * Actions on a GBIF node. Be aware that of 2013 Nodes DO NOT support the ContactInterface although
036 * advertised in this interface!!!
037 */
038@SuppressWarnings("unused")
039public interface NodeService extends NetworkEntityService<Node> {
040
041  /** Provides access to the organizations endorsed by a single node. */
042  PagingResponse<Organization> endorsedOrganizations(
043      @NotNull UUID nodeKey, @Nullable Pageable page);
044
045  /** Provides access to the organizations that are awaiting an endorsement approval. */
046  PagingResponse<Organization> pendingEndorsements(@Nullable Pageable page);
047
048  /**
049   * Provides access to the organizations that are awaiting an endorsement approval for the given
050   * node.
051   */
052  PagingResponse<Organization> pendingEndorsements(@NotNull UUID nodeKey, @Nullable Pageable page);
053
054  /**
055   * Provides the installations that are registered to organizations with an approved endorsement
056   * from the node.
057   */
058  PagingResponse<Installation> installations(@NotNull UUID nodeKey, @Nullable Pageable page);
059
060  /**
061   * Returns a node for a given country.
062   *
063   * @return the countries node or null if none exists
064   */
065  Node getByCountry(Country country);
066
067  /**
068   * Returns a list of all countries which do have a GBIF node.
069   *
070   * @return list of distinct countries having a GBIF node
071   */
072  List<Country> listNodeCountries();
073
074  /**
075   * Returns those countries considered active in GBIF. To be active a country must have a Node of
076   * type country present, that is either of voting or associate status.
077   *
078   * @return A list of countries ordered by iso code
079   */
080  List<Country> listActiveCountries();
081
082  /**
083   * Provides paging service to list datasets published, i.e. owned by organizations endorsed by the
084   * given node.
085   *
086   * @return list of datasets ordered by creation date with latest coming first
087   */
088  PagingResponse<Dataset> endorsedDatasets(@NotNull UUID nodeKey, @Nullable Pageable page);
089
090  /** Provides a simple suggest service. */
091  List<KeyTitleResult> suggest(@Nullable String q);
092
093  /**
094   * Provides paging service to list nodes that can be filtered by multiple parameters.
095   *
096   * @param searchParams {@link NodeRequestSearchParams}
097   * @return list of nodes ordered by creation date with the latest coming first
098   */
099  PagingResponse<Node> list(NodeRequestSearchParams searchParams);
100}