/* * Copyright 2015 the original author or authors. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package org.springframework.social.connect; import java.io.Serializable; /** * A link to a service provider user. * Allows the client application to access or update user information using the provider's API. * Exposes a set of operations that are common across all service providers, including * the ability to {@link #fetchUserProfile() access user profile information} and {@link #updateStatus(String) update user status}. * @author Keith Donald * @param <A> a strongly-typed binding to the service provider's API */ public interface Connection<A> extends Serializable { /** * The key identifying this connection. * @return A composite key that consists of the "providerId" plus "providerUserId"; for example, "facebook" and "125660". */ ConnectionKey getKey(); /** * A display name or label for this connection. * Should be suitable for display on a UI and distinguish this connection from others with the same provider. * Generally the full name or screen name of the connected provider user e.g. "Keith Donald" or "@kdonald". * May be null if this information is not public or not provided. * The value of this property may change if the user updates his or her profile. * @return the displayable name for the connection * @see #sync() */ String getDisplayName(); /** * The public URL of the connected user's profile at the provider's site. * A client application may use this value along with the displayName to generate a link to the user's profile on the provider's system. * May be null if this information is not public or not provided. * The value of this property may change if the user updates his or her profile. * @return the public URL for the connected user * @see #sync() */ String getProfileUrl(); /** * A link to a image that visualizes this connection. * Should visually distinguish this connection from others with the same provider. * Generally the small/thumbnail version of the connected provider user's profile picture. * May be null if this information is not public or not provided. * The value of this property may change if the user updates his or her profile. * @return a String containing the URL to the connection image * @see #sync() */ String getImageUrl(); /** * Sync's this connection object with the current state of the external user's profile. * Triggers locally cached profile fields to update if they have changed on the provider's system. */ void sync(); /** * Test this connection. * If false, indicates calls to the {@link #getApi() api} will fail. * Used to proactively test authorization credentials such as an API access token before invoking the service API. * @return true if the connection is valid */ boolean test(); /** * Returns true if this connection has expired. * An expired connection cannot be used; calls to {@link #test()} return false, and any service API invocations fail. * If expired, you may call {@link #refresh()} to renew the connection. * Not supported by all Connection implementations; always returns false if not supported. * @return true if the connection has expired */ boolean hasExpired(); /** * Refresh this connection. * Used to renew an expired connection. * If the refresh operation is successful, {@link #hasExpired()} returns false. * Not supported by all connection implementations; if not supported, this method is a no-op. */ void refresh(); /** * Fetch a normalized model of the user's profile on the provider system. * Capable of exposing the user's name, email, and username. * What is actually exposed depends on the provider and scope of this connection. * @return a normalized user profile associated with this connection. */ UserProfile fetchUserProfile(); /** * Update the user's status on the provider's system. * This method is a no-op if a status concept is not supported by the service provider. * @param message the status message */ void updateStatus(String message); /** * A Java binding to the service provider's native API. * @return the provider-specific API binding */ A getApi(); /** * Creates a data transfer object that can be used to persist the state of this connection. * Used to support the transfer of connection state between layers of the application, such as to the database layer. * @return a data transfer object containing details about the connection. */ ConnectionData createData(); }