/**
* Copyright (C) 2011 - present by OpenGamma Inc. and the OpenGamma group of companies
*
* Please see distribution for license.
*/
package com.opengamma.core.security;
import com.opengamma.DataNotFoundException;
import com.opengamma.core.Link;
import com.opengamma.core.LinkResolver;
import com.opengamma.id.ExternalIdBundle;
import com.opengamma.id.ObjectId;
import com.opengamma.id.UniqueId;
import com.opengamma.util.PublicAPI;
/**
* Resolver capable of providing securities.
* <p>
* This resolver provides lookup of a {@link Security security} to the engine functions.
* The lookup may require selecting a single "best match" from a set of potential options.
* The best match behavior is the key part that distinguishes one implementation from another.
* Best match selection may use a version-correction, configuration or code as appropriate.
* Implementations of this interface must specify the rules they use to best match.
* <p>
* This interface is read-only.
* Implementations must be thread-safe.
*/
@PublicAPI
public interface SecurityResolver extends LinkResolver<Security> {
/**
* Resolves the link to the provide the target security.
* <p>
* A link contains both an object and an external identifier bundle, although
* typically only one of these is populated. Since neither input exactly specifies
* a single version of a single security a best match is required.
* The resolver implementation is responsible for selecting the best match.
*
* @param link the link to be resolver, not null
* @return the resolved target, not null
* @throws DataNotFoundException if the target could not be resolved
* @throws RuntimeException if an error occurs
*/
@Override
Security resolve(Link<Security> link);
/**
* Gets a security by unique identifier.
* <p>
* A unique identifier exactly specifies a single security at a single version-correction.
* As such, there should be no complex matching issues in this lookup.
* However, if the underlying data store does not handle versioning correctly,
* then a best match selection may be required.
*
* @param uniqueId the unique identifier to find, not null
* @return the matched security, not null
* @throws IllegalArgumentException if the identifier is invalid
* @throws DataNotFoundException if the security could not be found
* @throws RuntimeException if an error occurs
*/
Security getSecurity(UniqueId uniqueId);
/**
* Gets a security by object identifier.
* <p>
* An object identifier exactly specifies a single security, but it provide no information
* about the version-correction required.
* As such, it is likely that multiple versions/corrections will match the object identifier.
* The resolver implementation is responsible for selecting the best match.
*
* @param objectId the object identifier to find, not null
* @return the matched security, not null
* @throws IllegalArgumentException if the identifier is invalid
* @throws DataNotFoundException if the security could not be found
* @throws RuntimeException if an error occurs
*/
Security getSecurity(ObjectId objectId);
/**
* Gets a security by external identifier bundle.
* <p>
* A bundle represents the set of external identifiers which in theory map to a single security.
* Unfortunately, not all external identifiers uniquely identify a single version of a single security.
* As such, it is likely that multiple versions/corrections of multiple different securities will match the bundle.
* The resolver implementation is responsible for selecting the best match.
*
* @param bundle the external identifier bundle to find, not null
* @return the matched security, not null
* @throws IllegalArgumentException if the identifier bundle is invalid
* @throws DataNotFoundException if the security could not be found
* @throws RuntimeException if an error occurs
*/
Security getSecurity(ExternalIdBundle bundle);
}