package org.springframework.roo.uaa;
import org.springframework.uaa.client.UaaService;
import org.springframework.uaa.client.VersionHelper;
import org.springframework.uaa.client.protobuf.UaaClient.Product;
/**
* Provides an API for any other Roo modules or add-ons to use to record UAA
* data.
* <p>
* This API ensures UAA conventions used by Roo are observed.
* <p>
* Implementations should perform the initial registration of the
* {@link #SPRING_ROO} product.
* <p>
* Implementations are required to buffer all notifications until such time as
* the {@link UaaService} reaches a privacy level where they can be successfully
* persisted. An implementation can rely on an invocation of
* {@link #flushIfPossible()} or attempt to write notifications on a subsequent
* call to a standard registration method. Implementations are therefore not
* required to establish a thread to handle flushing themselves, although they
* should make a final attempt on component deactivation.
*
* @author Ben Alex
* @since 1.1.1
*/
public interface UaaRegistrationService {
/**
* A HTTP URL of an "empty file" that add-ons can request if they wish to
* eagerly perform a UAA upload.
*/
String EMPTY_FILE_URL = "http://spring-roo-repository.springsource.org/empty_file.html";
/**
* Static representation of the Spring Roo product that should be used by
* any modules requiring a product representation.
*/
Product SPRING_ROO = VersionHelper.getProductFromManifest(
UaaRegistrationServiceImpl.class, "Spring Roo");
/**
* Indicates to attempt to flush the buffered notifications. If the
* {@link UaaService} is at a privacy level where it will accept
* registrations, the buffered notifications should be sent to the service.
* If the privacy level does not support this, the buffer should be
* preserved.
*/
void flushIfPossible();
/**
* Registers a new "feature use" within UAA. This method requires every
* feature to be a bundle symbolic name. This method permits (but does not
* require) the presentation of UTF-8 encoded custom JSON that will be
* stored as feature_data in the resulting UAA payload.
* <p>
* This method may be invoked without determining if the bundle symbolic
* name is public or not. This determination will be automatically made by
* implementations. Non-public bundle symbolic names will not be used.
*
* @param bundleSymbolicName a BSN to register the use of (required)
* @param customJson an optional JSON payload (can be null or an empty
* string if required)
*/
void registerBundleSymbolicNameUse(String bundleSymbolicName,
String customJson);
/**
* Registers a new "project" within UAA against the presented product. Note
* that UAA will use SHA-256 encoding for the project ID and it is never
* stored or transmitted in a non-hashed form.
* <p>
* A product is mandatory because a caller requiring a fallback product may
* use {@link #SPRING_ROO}. A project ID is mandatory because if low-level
* product information is available, this indicates a project configuration
* of some description is also available and therefore a project ID should
* also be available.
*
* @param product the product (required)
* @param projectId the project name to register (required)
*/
void registerProject(Product product, String projectId);
/**
* Attempts to transmit the data immediately to the server. This will only
* occur if the privacy level is acceptable and the {@link UaaService} is
* capable of transmission. Note this method should very rarely be
* necessary. It is only useful if an immediate transmission is desirable
* for some special reason (eg UAA is being used to convey user
* contributions to the server).
*/
void requestTransmission();
}