OSID - osid.repository.Asset Service Interface Definition

Interface	osid.repository.Asset
Implements	`osid.OsidObject`
	`osid.Aggregateable`
	`osid.Sourceable`
Used By	`osid.repository.AssetAdminSession`
	`osid.repository.AssetContent`
	`osid.repository.AssetList`
	`osid.repository.AssetLookupSession`
	`osid.resource.Resource`
Description	An `Asset` represents some digital content. Example assets might be a text document, an image, or a movie. The content data, and metadata related directly to the content format and quality, is accessed through `AssetContent. Assets`, like all `OsidObjects`, include a type a record to qualify the `Asset` and include additional data. The division between the `Asset` `Type` and `AssetContent` is to separate data describing the asset from data describing the format of the contents, allowing a consumer to select among multiple formats, sizes or levels of fidelity. An example is a photograph of the Bay Bridge. The content may deliver a JPEG in multiple resolutions where the `AssetContent` may also desribe size or compression factor for each one. The content may also include an uncompressed TIFF version. The `Asset` `Type` may be "photograph" indicating that the photo itself is the asset managed in this repository. Since an Asset may have multiple `AssetContent` structures, the decision of how many things to stuff inside a single asset comes down to if the content is actually a different format, or size, or quality, falling under the same creator, copyright, publisher and distribution rights as the original. This may, in some cases, provide a means to implement some accessibility, it doesn't handle the case where, to meet an accessibility requirement, one asset needs to be substituted for another. The Repository OSID manages this aspect outside the scope of the core `Asset` definition. `Assets` map to `AssetSubjects`. `AssetSubjects` are `OsidObjects` that capture a subject matter. In the above example, an `AssetSubject` may be defined for the Bay Bridge and include data describing the bridge. The single subject can map to multiple assets depicting the bridge providing a single entry for a search and a single place to describe a bridge. Bridges, as physical items, may also be described using the Resource OSID in which case the use of the `AssetSubject` acts as a cover for the underlying `Resource` to assist repository-only consumers. The `Asset` definition includes some basic copyright and related licensing information to assist in finding free-to-use content, or to convey the distribution restrictions that may be placed on the asset. Generally, if no data is available it is to be assumed that all rights are reserved. A publisher is applicable if the content of this `Asset` has been published. Not all `Assets` in this `Repository` may have a published status and such a status may effect the applicability of copyright law. To trace the source of an `Asset`, both a provider and source are defined. The provider indicates where this repository acquired the asset and the source indicates the original provider or copyright owner. In the case of a published asset, the source is the publisher. `Assets` also define methods to facilitate searches over time and space as it relates to the subject matter. This may at times be redundant with the `AssetSubject`. In the case of the Bay Bridge photograph, the temporal coverage may include 1936, when it opened, and/or indicate when the photo was taken to capture a current event of the bridge. The decision largeley depends on what desired effect is from a search. The spatial coverage may describe the gps coordinates of the bridge or describe the spatial area encompassed in the view. In either case, a "photograph" type may unambiguously defined methods to describe the exact time the photograph was taken and the location of the photographer. The core Asset defines methods to perform general searches and construct bibliographic entries without knowledge of a particular `Asset` or `AssetContent` record `Type`.
Method	getTitle
Description	Gets the proper title of this asset. This may be the same as the display name or the display name may be used for a less formal label.
Return	`osid.locale.DisplayText`		the title of this asset
Compliance	`mandatory`		This method must be implemented.
Method	isCopyrightStatusKnown
Description	Tests if the copyright status is known.
Return	`boolean`		`true` if the copyright status of this asset is known, `false` otherwise. If `false, isPublicDomain()`, `canDistributeVerbatim(), canDistributeAlterations() and canDistributeCompositions()` may also be `false`.
Compliance	`mandatory`		This method must be implemented.
Method	isPublicDomain
Description	Tests if this asset is in the public domain. An asset is in the public domain if copyright is not applicable, the copyright has expired, or the copyright owner has expressly relinquished the copyright.
Return	`boolean`		`true` if this asset is in the public domain, `false` otherwise. If `true`, `canDistributeVerbatim(), canDistributeAlterations() and canDistributeCompositions()` must also be `true`.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	getCopyright
Description	Gets the copyright statement and of this asset which identifies the current copyright holder. For an asset in the public domain, this method may return the original copyright statement although it may be no longer valid.
Return	`osid.locale.DisplayText`		the copyright statement or empty text if none available. An empty text does not imply the asset is not protected by copyright.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	getCopyrightRegistration
Description	Gets the copyright registration information for this asset.
Return	`string`		the copyright registration. An empty string means the registration status isn't known.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	canDistributeVerbatim
Description	Tests if there are any license restrictions on this asset that restrict the distribution, re-publication or public display of this asset, commercial or otherwise, without modification, alteration, or inclusion in other works. This method is intended to offer consumers a means of filtering out search results that restrict distribution for any purpose. The scope of this method does not include licensing that describes warranty disclaimers or attribution requirements. This method is intended for informational purposes only and does not replace or override the terms specified in a license agreement which may specify exceptions or additional restrictions.
Return	`boolean`		`true` if the asset can be distributed verbatim, `false` otherwise.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	canDistributeAlterations
Description	Tests if there are any license restrictions on this asset that restrict the distribution, re-publication or public display of any alterations or modifications to this asset, commercial or otherwise, for any purpose. This method is intended to offer consumers a means of filtering out search results that restrict the distribution or public display of any modification or alteration of the content or its metadata of any kind, including editing, translation, resampling, resizing and cropping. The scope of this method does not include licensing that describes warranty disclaimers or attribution requirements. This method is intended for informational purposes only and does not replace or override the terms specified in a license agreement which may specify exceptions or additional restrictions.
Return	`boolean`		`true` if the asset can be modified, `false` otherwise. If `true`, `canDistributeVerbatim()` must also be `true`.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	canDistributeCompositions
Description	Tests if there are any license restrictions on this asset that restrict the distribution, re-publication or public display of this asset as an inclusion within other content or composition, commercial or otherwise, for any purpose, including restrictions upon the distribution or license of the resulting composition. This method is intended to offer consumers a means of filtering out search results that restrict the use of this asset within compositions. The scope of this method does not include licensing that describes warranty disclaimers or attribution requirements. This method is intended for informational purposes only and does not replace or override the terms specified in a license agreement which may specify exceptions or additional restrictions.
Return	`boolean`		`true` if the asset can be part of a larger composition `false` otherwise. If `true`, `canDistributeVerbatim()` must also be `true`.
Errors	ILLEGAL_STATE		`isCopyrightStatusKnown()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	getSourceId
Description	Gets the `Resource Id` of the source of this asset. The source is the original owner of the copyright of this asset and may differ from the creator of this asset. The source for a published book written by Margaret Mitchell would be Macmillan. The source for an unpublished painting by Arthur Goodwin would be Arthur Goodwin. An `Asset` is `Sourceable` and also contains a provider identity. The provider is the entity that makes this digital asset available in this repository but may or may not be the publisher of the contents depicted in the asset. For example, a map published by Ticknor and Fields in 1848 may have a provider of Library of Congress and a source of Ticknor and Fields. If copied from a repository at Middlebury College, the provider would be Middlebury College and a source of Ticknor and Fields.
Return	`osid.id.Id`		the source `Id`
Compliance	`mandatory`		This method must be implemented.
Method	getSource
Description	Gets the `Resource` of the source of this asset. The source is the original owner of the copyright of this asset and may differ from the creator of this asset. The source for a published book written by Margaret Mitchell would be Macmillan. The source for an unpublished painting by Arthur Goodwin would be Arthur Goodwin.
Return	`osid.resource.Resource`		the source
Compliance	`mandatory`		This method must be implemented.
Method	getProviderLinkIds
Description	Gets the resource `Ids` representing the source of this asset in order from the most recent provider to the originating source.
Return	`osid.id.IdList`		the provider `Ids`
Compliance	`mandatory`		This method must be implemented.
Method	getProviderLinks
Description	Gets the `Resources` representing the source of this asset in order from the most recent provider to the originating source.
Return	`osid.resource.ResourceList`		the provider chain
Errors	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	getCreatedDate
Description	Gets the created date of this asset, which is generally not related to when the object representing the asset was created. The date returned may indicate that not much is known.
Return	`osid.calendaring.DateTime`		the created date
Compliance	`mandatory`		This method must be implemented.
Method	isPublished
Description	Tests if this asset has been published. Not all assets viewable in this repository may have been published. The source of a published asset indicates the publisher.
Return	`boolean`		true if this asset has been published, `false` if unpublished or its published status is not known
Compliance	`mandatory`		This method must be implemented.
Method	getPublishedDate
Description	Gets the published date of this asset. Unpublished assets have no published date. A published asset has a date available, however the date returned may indicate that not much is known.
Return	`osid.calendaring.DateTime`		the published date
Errors	ILLEGAL_STATE		`isPublished()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	getPrincipalCreditString
Description	Gets the credits of the principal people involved in the production of this asset as a display text.
Return	`osid.locale.DisplayText`		the principal credits
Compliance	`mandatory`		This method must be implemented.
Method	getAssetContentIds
Description	Gets the content `Ids` of this asset.
Return	`osid.id.IdList`		the asset content `Ids`
Compliance	`mandatory`		This method must be implemented.
Method	getAssetContents
Description	Gets the content of this asset.
Return	`osid.repository.AssetContentList`		the asset contents
Errors	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	isComposition
Description	Tetss if this asset is a representation of a composition of assets.
Return	`boolean`		true if this asset is a composition, `false` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	getCompositionId
Description	Gets the `Composition` `Id` corresponding to this asset.
Return	`osid.id.Id`		the composition `Id`
Errors	ILLEGAL_STATE		`isComposition()` is `false`
Compliance	`mandatory`		This method must be implemented.
Method	getComposition
Description	Gets the Composition corresponding to this asset.
Return	`osid.repository.Composition`		the composition
Errors	ILLEGAL_STATE		`isComposition()` is `false`
Errors	OPERATION_FAILED		unable to complete request
Compliance	`mandatory`		This method must be implemented.
Method	getAssetRecord
Description	Gets the asset record corresponding to the given `Asset` record `Type`.This method is used to retrieve an object implementing the requested record. The `assetRecordType` may be the `Type` returned in `getRecordTypes()` or any of its parents in a `Type` hierarchy where `hasRecordType(assetRecordType)` is `true`.
Parameters	`osid.type.Type`	`assetRecordType`	an asset record type
Return	`osid.repository.records.AssetRecord`		the asset record
Errors	NULL_ARGUMENT		`assetRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	UNSUPPORTED		`hasRecordType(assetRecordType)` is `false`
Compliance	`mandatory`		This method must be implemented.