core/src/main/java/org/jclouds/apis/ApiMetadata.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF 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.
 * 
 * @since 1.5
 */
@Beta
public interface ApiMetadata {

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

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

      /**
       * @see ApiMetadata#getContext()
       */
      B context(TypeToken<? extends Context> context);

      /**
       * @see ApiMetadata#getViews()
       */
      B view(Class<? extends View> view);
      
      /**
       * @see ApiMetadata#getViews()
       */
      B view(TypeToken<? extends View> view);

      /**
       * @see ApiMetadata#getViews()
       */
      B views(Set<TypeToken<? extends View>> 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<? extends Module> defaultModule);

      /**
       * @see ApiMetadata#getDefaultModules()
       */
      B defaultModules(Set<Class<? extends Module>> 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. ec2, openstack-nova)
    */
   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.
    * <p/>
    * For example, on OpenStack APIs, this could be: {@code Keystone url} <br/>
    * For file-based apis, this could be: {@code Path of byon.yaml}
    * <p/>
    * Default: {@code "https endpoint"}
    * <p/>
    * 
    * @return the name (display name) of an endpoint to this api (ex. Keystone
    *         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<String> 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}.
    */
   Optional<String> 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.
    * 
    * <h3>note</h3>
    * 
    * The type of endpoint is {@code String} as we permit endpoints that require
    * variable expansion.
    * 
    * ex.
    * 
    * <pre>
    * https://${jclouds.identity}.blob.core.windows.net
    * </pre>
    * 
    * @return the api's default endpoint, if known.
    */
   Optional<String> getDefaultEndpoint();

   /**
    * Explicitly identifies the login identity into a provider
    * 
    * @return the login identity into a provider, if known.
    */
   Optional<String> 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<String> 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<Class<? extends Module>> getDefaultModules();
   
   /**
    * 
    * @return the url for the API documentation related to this service
    */
   URI getDocumentation();

   /**
    * @return the primary context of this api, for example {@code ApiContext<EC2Api>}
    */
   TypeToken<? extends Context> getContext();
   
   /**
    * @return types of contexts this can be transformed into, for example {@code BlobStoreContext}
    */
   Set<TypeToken<? extends View>> getViews();

}