org.jclouds.apis.ApiMetadata Maven / Gradle / Ivy

Go to download
/**
 * Licensed to jclouds, Inc. (jclouds) under one or more
 * contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  jclouds licenses this file
 * to you 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.jclouds.apis;

import java.net.URI;
import java.util.Properties;
import java.util.Set;

import org.jclouds.Context;
import org.jclouds.View;
import org.jclouds.javax.annotation.Nullable;

import com.google.common.annotations.Beta;
import com.google.common.base.Optional;
import com.google.common.reflect.TypeToken;
import com.google.inject.Module;

/**
 * The ApiMetadata interface allows jclouds to provide a plugin framework for
 * gathering cloud api metadata.
 * 
 * @author Jeremy Whitlock , Adrian Cole
 * @since 1.5
 */
@Beta
public interface ApiMetadata {

   public static interface Builder>{
      /**
       * @see ApiMetadata#getId()
       */
      B id(String id);

      /**
       * @see ApiMetadata#getName()
       */
      B name(String name);

      /**
       * @see ApiMetadata#getContext()
       */
      B context(TypeToken context);

      /**
       * @see ApiMetadata#getViews()
       */
      B view(Class view);
      
      /**
       * @see ApiMetadata#getViews()
       */
      B view(TypeToken view);

      /**
       * @see ApiMetadata#getViews()
       */
      B views(Set> views);

      /**
       * @see ApiMetadata#getEndpointName()
       */
      B endpointName(String endpointName);

      /**
       * @see ApiMetadata#getIdentityName()
       */
      B identityName(String identityName);

      /**
       * @see ApiMetadata#getCredentialName()
       */
      B credentialName(@Nullable String credentialName);

      /**
       * @see ApiMetadata#getVersion()
       */
      B version(String version);

      /**
       * @see ApiMetadata#getBuildVersion()
       */
      B buildVersion(@Nullable String buildVersion);

      /**
       * @see ApiMetadata#getDefaultEndpoint()
       */
      B defaultEndpoint(@Nullable String defaultEndpoint);

      /**
       * @see ApiMetadata#getDefaultIdentity()
       */
      B defaultIdentity(@Nullable String defaultIdentity);

      /**
       * @see ApiMetadata#getDefaultCredential()
       */
      B defaultCredential(@Nullable String defaultCredential);

      /**
       * @see ApiMetadata#getDefaultProperties()
       */
      B defaultProperties(Properties defaultProperties);
      
      /**
       * @see ApiMetadata#getDefaultModules()
       */
      B defaultModule(Class defaultModule);

      /**
       * @see ApiMetadata#getDefaultModules()
       */
      B defaultModules(Set> defaultModules);
      
      /**
       * @see ApiMetadata#getDocumentation()
       */
      B documentation(URI documentation);

      ApiMetadata build();

      B fromApiMetadata(ApiMetadata from);
      
   }

   /**
    * @see Builder
    */
   Builder toBuilder();

   /**
    * 
    * @return the api's unique identifier (ex. vcloud, virtualbox)
    */
   String getId();

   /**
    * 
    * @return the name (display name) of the api (ex. EC2 Base API)
    */
   String getName();

   /**
    * 
    * The {@code endpointName} helps the user supply the correct data when
    * prompted.
    * 
    * For example, on OpenStack APIs, this could be: {@code Keystone url} 

    * For file-based apis, this could be: {@code Path of byon.yaml}
    * 

    * Default: {@code "https endpoint"}
    * 

    * 
    * @return the name (display name) of an endpoint to this api (ex. Keystone
    *         url, vCloud Director URL).
    */
   String getEndpointName();
   
   /**
    * 
    * @return the name (display name) of an identity on this api (ex. user,
    *         email, account, apikey, tenantId:username)
    */
   String getIdentityName();

   /**
    * Note: if the api doesn't need a credential, this will return absent.
    * 
    * @return the name (display name) of a credential on this api, if it is
    *         required (ex. password, secret, rsaKey)
    */
   Optional getCredentialName();

   /**
    * Explicitly identifies the version of an api.
    */
   String getVersion();

   /**
    * Explicitly identifies the build that the server jclouds connects to is
    * running.
    * 
    * For example, for virtualbox, the api version may be {@code 4.1.8} while
    * the build version is {@code 4.1.8r75467}. Or a vcloud endpoint may be api
    * version {@code 1.0} while the build is {@code 1.5.0.0.124312}
    */
   Optional getBuildVersion();

   /**
    * Explicitly identifies the most top-level endpoint to a service provider.
    * This helps differentiate two providers of the same api, or a different
    * environments providing the same api.
    * 
    * 
note
    * 
    * The type of endpoint is {@code String} as we permit endpoints that require
    * variable expansion.
    * 
    * ex.
    * 
    *     * https://${jclouds.identity}.blob.core.windows.net
    * 
    * 
    * @return the api's default endpoint, if known.
    */
   Optional getDefaultEndpoint();

   /**
    * Explicitly identifies the login identity into a provider
    * 
    * @return the login identity into a provider, if known.
    */
   Optional getDefaultIdentity();

   /**
    * Explicitly sets the secret, which when combined with the identity, will
    * create an authenticated subject or session
    * 
    * @return the api's default credential, if known.
    * @see #getDefaultIdentity
    * @see #getCredentialName
    */
   Optional getDefaultCredential();

   /**
    * Configuration Properties used when creating connections to this api
    * 
    * @return properties used to create connections to this api
    */
   Properties getDefaultProperties();

   /**
    * Modules that configure dependency injection for this context
    * 
    * @return modules that configure dependency injection for this context
    */
   Set> getDefaultModules();
   
   /**
    * 
    * @return the url for the API documentation related to this service
    */
   URI getDocumentation();

   /**
    * @return the primary context of this api, for example {@code RestContext}
    */
   TypeToken getContext();
   
   /**
    * @return types of contexts this can be transformed into, for example {@code BlobStoreContext}
    */
   Set> getViews();

}