/*******************************************************************************
* Copyright 2012 Geoscience Australia
*
* 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 au.gov.ga.earthsci.bookmark.model;
/**
* Represents a bookmark, used to store state that can be re-applied at a later
* date.
* <p/>
* Bookmarks contain zero or more {@link IBookmarkProperty}s, which capture the
* state stored by the bookmark.
*
* @author James Navin (james.navin@ga.gov.au)
*/
public interface IBookmark
{
/**
* Return the globally unique ID of this bookmark
*
* @return The ID of this bookmark
*/
String getId();
/**
* Return the name of this bookmark
*
* @return The name of this bookmark
*/
String getName();
/**
* Set the name of this bookmark, to allow for user edits etc.
*/
void setName(String name);
/**
* Return any metadata associated with this bookmark as a map of display
* strings keyed by
*
* @return The metadata associated with
*/
IBookmarkMetadata getMetadata();
/**
* Return the set of properties associated with this bookmark.
*
* @return The set of properties associated with this bookmark.
*/
IBookmarkProperty[] getProperties();
/**
* Return the property with the given type (if any).
*
* @param type
* The key for the type of property to return
*
* @return The property of the given type, or <code>null</code> if none
* exists.
*/
IBookmarkProperty getProperty(String type);
/**
* Add the given property to this bookmark.
*
* @param property
* The property to add.
*/
void addProperty(IBookmarkProperty property);
/**
* Remove the property of the given type from this bookmark, if it exists
*
* @param type
* The type of the property to remove
*
* @return The removed property, or <code>null</code> if none is removed
*/
IBookmarkProperty removeProperty(String type);
/**
* Remove the given property from this bookmark, if it exists
*
* @param p
* The property to remove
*
* @return <code>true</code> if the property was removed; <code>false</code>
* otherwise
*/
boolean removeProperty(IBookmarkProperty p);
/**
* Return whether a property exists in this bookmark with the given type
*
* @param type
* The property type to check for existence
*
* @return <code>true</code> if the property exists on this bookmark;
* <code>false</code> otherwise.
*/
boolean hasProperty(String type);
/**
* Return the duration (in milliseconds) that the system should take when
* transitioning to this bookmark state from the current world state.
* <p/>
* If the global default is to be used, this method will return
* <code>null</code>.
*
* @return The duration (in milliseconds) that the system should take when
* transitioning to this bookmark
*/
Long getTransitionDuration();
}