AssetReference (Cumulus Java Classes Documentation)

java.lang.Object
- com.canto.cumulus.fieldvalue.AssetReference

All Implemented Interfaces:

FieldValue, java.lang.AutoCloseable
```
public class AssetReference
extends java.lang.Object
implements FieldValue, java.lang.AutoCloseable
```
A field value wrapper for an asset reference field, e.g. a field with the GUID GUID.UID_REC_ASSET_REFERENCE or GUID.UID_REC_CHECKOUT_LOCATION. Use Item.getAssetReferenceValue(com.canto.cumulus.GUID) to get this wrapper class object. You can then use Item.setAssetReferenceValue(com.canto.cumulus.GUID, AssetReference) to set the field value back into the item.

Since:

8.0

Constructor Summary

Constructors
Constructor and Description
`AssetReference(CumulusSession session, java.lang.String pathNameOrXML, java.lang.String assetHandlingSet)` Create a new asset reference object from the given data.

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`clearValue()` You need to set the field value of an item using this field value wrapper and then call `Item.save()` to save this change back to the catalog.
`void`	`close()` Releases all native resources associated with this instance.
`int`	`countLevels()` Return the number of levels of this asset reference.
`int`	`countParts()` Get the number of asset reference parts that this asset reference consists of.
`boolean`	`equals(java.lang.Object o)`
`Asset`	`getAsset(boolean allowProxyAsset)` Resolves the asset reference data and returns the asset object, using the default asset handling set.
`java.lang.String`	`getAsXML()` Returns the asset references in XML format.
`CumulusSession`	`getCumulusSession()` Get the Cumulus session that belongs to this asset reference.
`java.lang.String`	`getDisplayString()` Return the field's value as a string that can be displayed to the user.
`java.lang.String`	`getDisplayString(java.util.Locale locale)` Return the field's value as a string that can be displayed to the user.
`AssetReferencePart`	`getPart(GUID classID)` Returns an asset reference by the class ID of the `AssetStorage` module that created it.
`AssetReferencePart`	`getPart(int index)` Get a part of this reference by index.
`java.util.Set<GUID>`	`getPartClassIDs(int level)` Returns the set of class IDs that are available for the specified level.
`int`	`hashCode()`
`boolean`	`hasValue()` Return whether this field has a value.
`void`	`setFromDisplayString(java.util.Locale locale, java.lang.String value)` This method is not supported for asset reference values.
`void`	`setFromDisplayString(java.lang.String value)` This method is not supported for asset reference values.
`boolean`	`supportsVersioning()` Return whether this asset reference supports versioning, meaning that is allows (after resolving it to an `Asset` object to check it out and check a new version back in.

Methods inherited from class java.lang.Object
getClass, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - AssetReference
```
public AssetReference(CumulusSession session,
              java.lang.String pathNameOrXML,
              java.lang.String assetHandlingSet)
```
    Create a new asset reference object from the given data.
    
    Parameters:
    session - The Cumulus session to use.
    pathNameOrXML - Either a patch name for a native file or a URL or the XML representation of an asset reference field value.
    assetHandlingSet - The name of the asset handling set to use.
- Method Detail
  - hasValue
```
public boolean hasValue()
```
    Return whether this field has a value.
    
    Specified by:
    
    hasValue in interface FieldValue
    
    Returns:
    true if the field has a value, false otherwise.
  - clearValue
```
public void clearValue()
```
    You need to set the field value of an item using this field value wrapper and then call Item.save() to save this change back to the catalog.
    
    Specified by:
    
    clearValue in interface FieldValue
  - getDisplayString
```
public java.lang.String getDisplayString()
```
    Return the field's value as a string that can be displayed to the user. This method creates a string that contains all parts with their asset storage name and display information.
    
    Specified by:
    
    getDisplayString in interface FieldValue
    
    Returns:
    A string representation of the field value to be displayed (an empty string if it has no value).
  - getDisplayString
```
public java.lang.String getDisplayString(java.util.Locale locale)
```
    Return the field's value as a string that can be displayed to the user. This method creates a string that contains all parts with their asset storage name and display information.
    
    Specified by:
    
    getDisplayString in interface FieldValue
    
    Parameters:
    locale - Unused parameter.
    
    Returns:
    A string representation of the field value to be displayed (an empty string if it has no value).
  - setFromDisplayString
```
public void setFromDisplayString(java.lang.String value)
                          throws InvalidArgumentException
```
    This method is not supported for asset reference values.
    
    Specified by:
    
    setFromDisplayString in interface FieldValue
    
    Parameters:
    value - The display string to set the value from.
    
    Throws:
    
    InvalidArgumentException - if the display string is not of the right format.
  - setFromDisplayString
```
public void setFromDisplayString(java.util.Locale locale,
                        java.lang.String value)
                          throws InvalidArgumentException
```
    This method is not supported for asset reference values.
    
    Specified by:
    
    setFromDisplayString in interface FieldValue
    
    Parameters:
    locale - The locale to use for formatting and language selection.
    value - The display string to set the value from.
    
    Throws:
    
    InvalidArgumentException - if the display string is not of the right format.
  - getCumulusSession
```
public CumulusSession getCumulusSession()
```
    Get the Cumulus session that belongs to this asset reference.
    
    Returns:
    The asset reference's session.
  - supportsVersioning
```
public boolean supportsVersioning()
```
    Return whether this asset reference supports versioning, meaning that is allows (after resolving it to an Asset object to check it out and check a new version back in.
    
    Returns:
    true if this asset reference supports versioning.
  - countLevels
```
public int countLevels()
```
    Return the number of levels of this asset reference. Each asset reference may consist of more that one level if it references an asset that is contained in another asset (e.g. a TIFF packed into a ZIP archive).
    
    Returns:
    The number of levels of this asset reference.
  - countParts
```
public int countParts()
```
    Get the number of asset reference parts that this asset reference consists of. These parts are arranged by levels. Please check the level of each part to find out in which level this part is used.
    
    Returns:
    The number of parts that this asset reference consists of.
  - getPart
```
public AssetReferencePart getPart(int index)
```
    Get a part of this reference by index.
    
    Parameters:
    index - Zero-based index into the parts.
    
    Returns:
    The part at the given index.
  - getPart
```
public AssetReferencePart getPart(GUID classID)
```
    Returns an asset reference by the class ID of the AssetStorage module that created it.
    Possible values are:
    Parameters:
    classID - the class ID of the AssetStorage module that created the asset reference part.
    
    Returns:
    an asset reference part.
    
    Throws:
    
    CumulusException - if the specified part cannot be found.
    See Also:
    getPart(int)
  - getPartClassIDs
```
public java.util.Set<GUID> getPartClassIDs(int level)
```
    Returns the set of class IDs that are available for the specified level.
    
    Parameters:
    level - level to get the class IDs for
    
    Returns:
    set of class IDs
    Since:
    
    8.6
  - getAsXML
```
public java.lang.String getAsXML()
```
    Returns the asset references in XML format.
    
    Returns:
    the asset references in XML format.
    See Also:
    AssetReference(com.canto.cumulus.CumulusSession, String, String)
  - getAsset
```
public Asset getAsset(boolean allowProxyAsset)
               throws UnresolvableAssetReferenceException,
                      CumulusException
```
    Resolves the asset reference data and returns the asset object, using the default asset handling set. The asset must be accessible (online) to be able to resolve the asset reference data. Depending on the parameter it may be accessible only to the Cumulus Server, not to the client.
    
    Parameters:
    allowProxyAsset - if true then Cumulus may return a proxy asset instead of the real one. A proxy asset is created if the client can not access the real asset but a server has access. If the user has the permission to transfer assets, Cumulus creates a proxy asset that allows to access the properties of an asset (including the data streams) but will not provide a container asset and access to sub-assets.
    
    Returns:
    the Asset object for accessing the asset.
    
    Throws:
    
    UnresolvableAssetReferenceException - in case the asset reference cannot be resolved
    
    CumulusException - in case of any unknown error
  - close
```
public void close()
```
    Releases all native resources associated with this instance.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
    
    Since:
    
    8.6
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object

www.canto.com
Canto, the Canto logo, the Cumulus logo, and Cumulus are registered trademarks of Canto GmbH, registered in the U.S. and other countries.

Class AssetReference

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

AssetReference

Method Detail

hasValue

clearValue

getDisplayString

getDisplayString

setFromDisplayString

setFromDisplayString

getCumulusSession

supportsVersioning

countLevels

countParts

getPart

getPart

getPartClassIDs

getAsXML

getAsset

close

equals

hashCode