org.cdecode.firebase.api.database.DatabaseReference Maven / Gradle / Ivy
/*
* Copyright 2017 Google Inc. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
* You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
* for the specific language governing permissions and limitations under the License.
*/
package org.cdecode.firebase.api.database;
import java.util.Map;
import org.cdecode.firebase.api.tasks.Task;
/**
* A Firebase reference represents a particular location in your Database and can be used for reading or writing data to that Database location.
*
* This class is the starting point for all Database operations. After you've initialized it with a URL, you can use it to read data, write data, and to create
* new DatabaseReferences.
*/
public interface DatabaseReference
extends Query {
/**
* Get a reference to location relative to this one
*
* @param pathString The relative path from this reference to the new one that should be created
* @return A new DatabaseReference to the given path
*/
public DatabaseReference child(final String pathString);
/**
* Create a reference to an auto-generated child location. The child key is generated client-side and incorporates an estimate of the server's time for
* sorting purposes. Locations generated on a single client will be sorted in the order that they are created, and will be sorted approximately in order
* across all clients.
*
* @return A DatabaseReference pointing to the new location
*/
public DatabaseReference push();
/**
* Set the data at this location to the given value. Passing null to setValue() will delete the data at the specified location. The native types accepted by
* this method for the value correspond to the JSON types:
*
* - Boolean
*
- Long
*
- Double
*
- Map<String, Object>
*
- List<Object>
*
*
*
* In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
*
* - The class must have a default constructor that takes no arguments
*
- The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an
* instance is deserialized
*
*
*
* Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null
* values.
*
* @param value The value to set at this location
* @return The {@link Task} for this operation.
*/
public Task setValue(final Object value);
// Set priority
/**
* Set the data and priority to the given values. Passing null to setValue() will delete the data at the specified location. The native types accepted by
* this method for the value correspond to the JSON types:
*
* - Boolean
*
- Long
*
- Double
*
- Map<String, Object>
*
- List<Object>
*
*
*
* In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
*
* - The class must have a default constructor that takes no arguments
*
- The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an
* instance is deserialized
*
*
*
* Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null
* values.
*
* @param value The value to set at this location
* @param priority The priority to set at this location
* @return The {@link Task} for this operation.
*/
public Task setValue(final Object value, final Object priority);
/**
* Set the data at this location to the given value. Passing null to setValue() will delete the data at the specified location. The native types accepted by
* this method for the value correspond to the JSON types:
*
* - Boolean
*
- Long
*
- Double
*
- Map<String, Object>
*
- List<Object>
*
*
*
* In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
*
* - The class must have a default constructor that takes no arguments
*
- The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an
* instance is deserialized
*
*
*
* Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null
* values.
*
* @param value The value to set at this location
* @param listener A listener that will be triggered with the results of the operation
*/
public void setValue(final Object value, final CompletionListener listener);
/**
* Set the data and priority to the given values. The native types accepted by this method for the value correspond to the JSON types:
*
* - Boolean
*
- Long
*
- Double
*
- Map<String, Object>
*
- List<Object>
*
*
*
* In addition, you can set instances of your own class into this location, provided they satisfy the following constraints:
*
* - The class must have a default constructor that takes no arguments
*
- The class must define public getters for the properties to be assigned. Properties without a public getter will be set to their default value when an
* instance is deserialized
*
*
*
* Generic collections of objects that satisfy the above constraints are also permitted, i.e. Map<String, MyPOJO>, as well as null
* values.
*
* @param value The value to set at this location
* @param priority The priority to set at this location
* @param listener A listener that will be triggered with the results of the operation
*/
public void setValue(final Object value, final Object priority, final CompletionListener listener);
/**
* Set a priority for the data at this Database location. Priorities can be used to provide a custom ordering for the children at a location (if no
* priorities are specified, the children are ordered by key).
*
* You cannot set a priority on an empty location. For this reason setValue(data, priority) should be used when setting initial data with a specific
* priority and setPriority should be used when updating the priority of existing data.
*
* Children are sorted based on this priority using the following rules:
*
* - Children with no priority come first.
*
- Children with a number as their priority come next. They are sorted numerically by priority (small to large).
*
- Children with a string as their priority come last. They are sorted lexicographically by priority.
*
- Whenever two children have the same priority (including no priority), they are sorted by key. Numeric keys come first (sorted numerically), followed
* by the remaining keys (sorted lexicographically).
*
*
* Note that numerical priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are
* treated as numeric only when they can be parsed as a 32-bit integer.
*
* @param priority The priority to set at the specified location.
* @return The {@link Task} for this operation.
*/
public Task setPriority(final Object priority);
/**
* Set a priority for the data at this Database location. Priorities can be used to provide a custom ordering for the children at a location (if no
* priorities are specified, the children are ordered by key).
*
* You cannot set a priority on an empty location. For this reason setValue(data, priority) should be used when setting initial data with a specific
* priority and setPriority should be used when updating the priority of existing data.
*
* Children are sorted based on this priority using the following rules:
*
* - Children with no priority come first.
*
- Children with a number as their priority come next. They are sorted numerically by priority (small to large).
*
- Children with a string as their priority come last. They are sorted lexicographically by priority.
*
- Whenever two children have the same priority (including no priority), they are sorted by key. Numeric keys come first (sorted numerically), followed
* by the remaining keys (sorted lexicographically).
*
*
* Note that numerical priorities are parsed and ordered as IEEE 754 double-precision floating-point numbers. Keys are always stored as strings and are
* treated as numeric only when they can be parsed as a 32-bit integer.
*
* @param priority The priority to set at the specified location.
* @param listener A listener that will be triggered with results of the operation
*/
public void setPriority(final Object priority, final CompletionListener listener);
/**
* Update the specific child keys to the specified values. Passing null in a map to updateChildren() will remove the value at the specified location.
*
* @param update The paths to update and their new values
* @return The {@link Task} for this operation.
*/
public Task updateChildren(final Map update);
// Access to disconnect operations
/**
* Update the specific child keys to the specified values. Passing null in a map to updateChildren() will remove the value at the specified location.
*
* @param update The paths to update and their new values
* @param listener A listener that will be triggered with results of the operation
*/
public void updateChildren(final Map update, final CompletionListener listener);
/**
* Set the value at this location to 'null'
*
* @return The {@link Task} for this operation.
*/
public Task removeValue();
// Manual Connection Management
/*
* The Firebase Database client automatically maintains a persistent connection to the Database server, which will remain active indefinitely and reconnect
* when disconnected. However, the goOffline( ) and goOnline( ) methods may be used to manually control the client connection in cases where a persistent
* connection is undesirable. While offline, the Firebase Database client will no longer receive data updates from the server. However, all Database
* operations performed locally will continue to immediately fire events, allowing your application to continue behaving normally. Additionally, each
* operation performed locally will automatically be queued and retried upon reconnection to the Database server.
To reconnect to the Database server and
* begin receiving remote events, see goOnline( ). Once the connection is reestablished, the Database client will transmit the appropriate data and fire the
* appropriate events so that your client "catches up" automatically.
*/
/**
* Set the value at this location to 'null'
*
* @param listener A listener that will be triggered when the operation is complete
*/
public void removeValue(final CompletionListener listener);
/**
* Provides access to disconnect operations at this location
*
* @return An object for managing disconnect operations at this location
*/
public OnDisconnect onDisconnect();
// Getters and other auxiliary methods
/**
* @return The full location url for this reference
*/
@Override
public String toString();
/**
* @return A DatabaseReference to the parent location, or null if this instance references the root location
*/
public DatabaseReference getParent();
/**
* @return A reference to the root location of this Firebase Database
*/
public DatabaseReference getRoot();
/**
* @return The last token in the location pointed to by this reference
*/
public String getKey();
@Override
public boolean equals(final Object other);
@Override
public int hashCode();
/**
* This interface is used as a method of being notified when an operation has been acknowledged by the Database servers and can be considered complete
*
* @since 1.1
*/
public interface CompletionListener {
/**
* This method will be triggered when the operation has either succeeded or failed. If it has failed, an error will be given. If it has succeeded, the
* error will be null
*
* @param error A description of any errors that occurred or null on success
* @param ref A reference to the specified Firebase Database location
*/
void onComplete(final DatabaseError error, final DatabaseReference ref);
}
}