org.ctoolkit.restapi.client.RestFacade Maven / Gradle / Ivy
Show all versions of ctoolkit-rest-facade-api Show documentation
/*
* Copyright (c) 2017 Comvai, s.r.o. All Rights Reserved.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
*/
package org.ctoolkit.restapi.client;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import java.util.Collection;
/**
* Fluent facade API to allow perform REST operations of various APIs through a single interface.
*
* @author Aurel Medvegy
*/
public interface RestFacade
{
/**
* ISO-8601 (RFC-3339), date format.
* Recommended messaging (Publish/Subscribe)
*
* It includes:
*
* - 2018-12-28T20:00:30.999Z - Millisecond fractions, UTC/Zulu time, has no offset
* - 2018-12-28T21:00:30.999+01:00 - Millisecond fractions, CET time
*
*/
String DATE_FORMAT = "yyyy-MM-dd'T'HH:mm:ss.SSSXXX";
/**
* Create a new in memory resource instance of requested type.
*
* Note: Based on the concrete implementation of the resource it may result in a remote call
* in order to get a more specific resource instance. Either created locally with 'new'
* operator or based on the implementation a remote call might be executed to get a 'new' instance
* initialized with default values and given parameters if any.
*
* Note: the remote call itself will be executed by request instance {@link PayloadRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the type of resource to create
* @return the fluent action for consequent configurations
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
PayloadRequest newInstance( @Nonnull Class resource );
/**
* Upload a media and related metadata represented by given resource.
*
* @param resource the resource that acts as a metadata to be inserted or updated
* @return the fluent action, consequent call will let you provide and configure a media to be uploaded
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
UploadMediaProvider upload( @Nonnull T resource );
/**
* Download a media for given resource.
*
* @param resource the type of the resource to download
* @return the fluent action, consequent call will download requested type
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
DownloadMediaProvider download( @Nonnull Class resource );
/**
* Retrieve a resource instance of requested type and identifier.
*
* Note: the remote call itself will be executed by request instance {@link RetrievalRequest}
* with possibility to provide optional parameters or locale.
*
* @param resource the type of resource to get
* @return the fluent action, consequent call will return concrete resource instance for given type and identifier,
* otherwise returns null
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
SingleRetrievalIdentification get( @Nonnull Class resource );
/**
* Find the list of resource instance of given type and filtering criteria.
*
* Note: the remote call itself will be executed by request instance {@link ListRetrievalRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the type of resource to find
* @return the fluent action, consequent call will return list of resource instance matching filtering criteria,
* otherwise returns empty list
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
ListRetrievalRequest list( @Nonnull Class resource );
/**
* Find the list of resource instance of given type and filtering criteria.
*
* Note: the remote call itself will be executed by request instance {@link ListRetrievalRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the type of resource to find
* @param parent the unique identifier of the parent resource as an owner of given resource if any
* @return the fluent action, consequent call will return list of resource instance matching filtering criteria,
* otherwise returns empty list
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
ListRetrievalRequest list( @Nonnull Class resource, @Nullable Identifier parent );
/**
* Insert a resource instance.
*
* Note: the remote call itself will be executed by request instance {@link PayloadRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the resource instance of concrete type to insert
* @return the fluent action, consequent call will return newly inserted instance
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
PayloadRequest insert( @Nonnull T resource );
/**
* Insert a resource instance.
*
* Note: the remote call itself will be executed by request instance {@link PayloadRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the resource instance of concrete type to insert
* @param parent the resource parent identifier
* @return the fluent action, consequent call will return newly inserted instance
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
PayloadRequest insert( @Nonnull T resource, @Nullable Identifier parent );
/**
* Update the given resource instance.
*
* Note: the remote call itself will be executed by request instance {@link PayloadRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the resource instance of concrete type
* @return the fluent action, consequent call will return updated instance
* @throws HttpFailureException a runtime exception wrapping all REST (status code) related exceptions
*/
UpdateIdentification update( @Nonnull T resource );
/**
* Remove the resource type for given identifier.
*
* Note: the remote call itself will be executed by request instance {@link SimpleRequest} with possibility
* to provide optional parameters or locale.
*
* @param resource the type of resource to remove
* @return the fluent action
* @throws HttpFailureException if not matching request URI has found
*/
DeleteIdentification delete( @Nonnull Class resource );
/**
* Get already initialized underlying API specific client instance to work with.
*
* @param type the concrete class type of the underlying client
* @return the underlying client instance
* @throws NotFoundException if unknown client type has been requested
*/
C client( @Nonnull Class type );
/**
* Same as {@link #impersonate(Collection, String, String)}
* where scopes parameter will be the same as for default configuration.
*
* @param userEmail the email address of the user to impersonate
* @param api the short name of an API that has been installed with this facade
* @throws IllegalArgumentException if requested API is not initialized or impersonate is not supported
*/
void impersonate( @Nonnull String userEmail, @Nonnull String api );
/**
* Sets the email address of the user and API scopes the application is trying to impersonate in the service
* account flow for current thread (only) of the specified API.
*
* It enables a service account (with domain-wide delegation enabled) to impersonate a managed user,
* ie. act on behalf of an identity, via domain-wide delegation of authority (for example G-Suite).
* An administrator of a target domain must configure service account's Client ID
* to allow access to desired domain.
*
* @param scopes the scopes for use with API
* @param userEmail the email address of the user to impersonate
* @param api the short name of an API that has been installed with this facade
* @throws IllegalArgumentException if requested API is not initialized or impersonate is not supported
*/
void impersonate( @Nonnull Collection scopes, @Nonnull String userEmail, @Nonnull String api );
}