---
title: The Referencing System
---

The referencing system allows the user to have an automatically updating copy of a given resource.

A `ResourceReference` can be gotten by calling one of the two `Mixson.registerReference` methods, which are defined
as follows:
```java
public static ResourceReference<JsonElement> registerReference(int priority, Index index, String referenceName);

public static <T> ResourceReference<T> registerReference(MixsonCodec<T> codec, int priority, Index index, String referenceName);
```

Similar to the event register methods, the first method is specifically for dealing with `JsonElement`s. The second
method allows any resource to be processed by passing it a `MixsonCodec`. Note that the resource inside a reference
is a copy, not a mutable value.

References are hardcoded to have an ErrorPolicy of `THROW`.

The `ResourceReference` object can be used however and provides several methods of use to the user.

---

## retrieve
```java
Optional<T> retrieve();
```
**Returns**: an `Optional<T>` containing the resource. Calling this method does not mutate the resource nor
the reference.

## consume
```java
Optional<T> consume();
```
**Returns**: an `Optional<T>` containing the resource. Calling this method removes the resource from the reference.

## fulfill
```java
void fulfill(T elem);
```
**Parameter "elem"**: the `elem` is to be the resource to be stored in the reference. Calling this method overwrites the
resource already stored in the reference.

## getName
```java
Optional<T> getName();
```
**Returns**: the `String` name of the reference.

## getIndex
```java
Index getIndex();
```
**Returns**: the `Index` of the reference.

## getUuid
```java
UUID getUuid();
```
**Returns**: the `UUID` of the reference.