org.linguafranca.pwdb.Entry Maven / Gradle / Ivy
/*
* Copyright 2015 Jo Rabin
*
* 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.linguafranca.pwdb;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import java.util.*;
/**
* Interface for a Database Entry. Database entries provide support
* at least for the Standard Properties of
*
* - Title
*
- Username
*
- Password
*
- URL
*
- Notes
*
*
* Entries have a UUID and have an Icon, which are not properties.
*
*
Support for additional textual properties may be provided
* by a database implementation.
*
*
Entries provide support for tracking when they are used.
* At some point support for accessing a history of modifications
* may be added to this interface
*
* @author Jo
*/
public interface Entry , G extends Group, E extends Entry, I extends Icon> {
/**
* Standard properties are attributes of Entries that are accessible either by
* dedicated methods, such as getPassword, or by {@link #getProperty(String)}
*/
String STANDARD_PROPERTY_NAME_USER_NAME = "UserName";
String STANDARD_PROPERTY_NAME_PASSWORD = "Password";
String STANDARD_PROPERTY_NAME_URL = "URL";
String STANDARD_PROPERTY_NAME_TITLE = "Title";
String STANDARD_PROPERTY_NAME_NOTES = "Notes";
List STANDARD_PROPERTY_NAMES = Collections.unmodifiableList(Arrays.asList(
STANDARD_PROPERTY_NAME_USER_NAME,
STANDARD_PROPERTY_NAME_PASSWORD,
STANDARD_PROPERTY_NAME_URL,
STANDARD_PROPERTY_NAME_TITLE,
STANDARD_PROPERTY_NAME_NOTES));
/**
* Interface to implement when using the {@link #match(Entry.Matcher)}
* method
*/
interface Matcher {
boolean matches(Entry entry);
}
/**
* Determines if an entry matches the text supplied. A match is recorded if
* the text matches the Url, Title, Username or Notes. Match means that any
* portion of the field to lower case contains the field supplied, to lowercase.
*
* @param text the text to find
* @return true if this entry matches the text
*/
boolean match(String text);
/**
* Returns the result of applying the matcher to this Entry
*
* @param matcher the matcher to use
* @return the result of applying the matcher
*/
boolean match(Matcher matcher);
/**
* Returns an XPath-like representation of this
* entry's ancestor groups and the title of this entry.
*/
String getPath();
/**
* Gets the value of a property.
*
* All implementations of Entry are required to support reading and writing of
* {@link #STANDARD_PROPERTY_NAMES}.
* @param name the name of the property to get
* @return a value or null if the property is not known, or if setting of arbitrary properties is not supported
* @see Database#supportsNonStandardPropertyNames()
*/
String getProperty(String name);
/**
* Sets the value of a property.
*
*
Other than the {@link #STANDARD_PROPERTY_NAMES} support for this methd is optional.
*
* @param name the name of the property to set
* @param value the value to set it to
* @throws UnsupportedOperationException if the name is not one of the standard properties and
* non-standard properties are not supported
* @see Database#supportsNonStandardPropertyNames()
*/
void setProperty(String name, String value);
/**
* Removes this non-standard property, if it exists.
*
* @return true if the property exists and was removed, false otherwise
* @param name the value of the property to remove
* @throws UnsupportedOperationException if non-standard properties are not supported
* @throws IllegalArgumentException if name is a standard property
* @see Database#supportsNonStandardPropertyNames()
*/
boolean removeProperty(String name) throws IllegalArgumentException, UnsupportedOperationException;
/**
* Returns a list of property names known to the entry.
*
*
All implementations of Entry are required to support reading and writing of
* {@link #STANDARD_PROPERTY_NAMES}.
* @return a list that is modifiable by the caller without affecting the Entry.
*/
List getPropertyNames();
/**
* Gets the value of a binary property.
*
* Support for this method is optional.
*
* @param name the name of the property to get
* @return a value or null if the property is not known, or if setting of arbitrary properties is not supported
* @see Database#supportsBinaryProperties
*/
byte[] getBinaryProperty(String name);
/**
* Sets the value of a binary property.
*
*
Support for this method is optional.
*
* @param name the name of the property to set
* @param value the value to set it to
* @throws UnsupportedOperationException if binary properties are not supported
* @see Database#supportsBinaryProperties()
*/
void setBinaryProperty(String name, byte[] value);
/**
* Removes this binary property, if it exists.
*
* @return true if the property was removed, false otherwise
* @param name the value of the property to remove
* @throws UnsupportedOperationException if binary properties are not supported
* @see Database#supportsBinaryProperties()
*/
boolean removeBinaryProperty(String name) throws UnsupportedOperationException;
/**
* Returns a list of binary property names known to the entry.
*
*
All implementations of Entry are required to support reading and writing of
* {@link #STANDARD_PROPERTY_NAMES}.
* @return a list that is modifiable by the caller without affecting the Entry.
* @throws UnsupportedOperationException if binary properties are not supported
* @see Database#supportsBinaryProperties()
*/
List getBinaryPropertyNames();
/**
* Get the parent of this entry
* @return a parent or null if this entry currently does not have a parent
*/
@Nullable G getParent();
/**
* Get the UUID of this entry. Databases (like KDB) that do not natively support
* UUIDs must provide a surrogate here.
*
* @return a UUID
*/
@NotNull UUID getUuid();
/**
* Get the username field of this entry
* @return a username
*/
String getUsername();
/**
* set the username
* @param username username to set
*/
void setUsername(String username);
/**
* Returns true if this username to lowercase contains the passed username to lowercase.
* @param username a username to match
* @return true if matches
*/
boolean matchUsername(String username);
/**
* Gets the (unencrypted) password field for this entry.
*
* Implementations should Touch LastAccessedTime when this method is called.
*
* @return a password
*/
String getPassword();
/**
* Sets the plaintext password for this Entry.
*
*
Implementations should Touch LastModifiedTime when this method is called.
*
* @param pass a password
*/
void setPassword(String pass);
/**
* Gets the URL for this entry.
*
*
Implementations should Touch LastAccessedTime when this method is called.
*
* @return a string representation of a URL
*/
String getUrl();
/**
* Sets the url for this Entry.
*
*
Implementations should Touch LastModifiedTime when this method is called.
*
* @param url the value to set
*/
void setUrl(String url);
/**
* Returns true if this url to lowercase contains the passed url to lowercase.
* @param url a string to match
* @return true if matches
*/
boolean matchUrl(String url);
/**
* Gets the title of this entry.
*
*
Implementations should Touch LastAccessedTime when this method is called.
*
* @return a title
*/
String getTitle();
/**
* Sets the title for this Entry.
*
*
Implementations should Touch LastModifiedTime when this method is called.
*
* @param title the value to set
*/
void setTitle(String title);
/**
* Returns true if this title to lowercase contains the passed title to lowercase.
* @param text a string to match
* @return true if matches
*/
boolean matchTitle(String text);
/**
* Gets the notes field for this entry.
*
*
Implementations should Touch LastAccessedTime when this method is called.
*
* @return the notes field
*/
String getNotes();
/**
* Sets the notes for this Entry.
*
*
Implementations should Touch LastModifiedTime when this method is called.
*
* @param notes the value to set
*/
void setNotes(String notes);
/**
* Returns true if the notes to lowercase contains the passed string to lowercase.
* @param text a string to match
* @return true if matches
*/
boolean matchNotes(String text);
/**
* Returns the {@link Icon} associated with this entry.
* @return an Icon
*/
I getIcon();
/**
* Sets the {@link Icon} associated with this entry.
* @param icon an Icon
*/
void setIcon(I icon);
/**
* Returns the date at which any value was retrieved from this entry.
*
* Implementations SHOULD set this to the creation date or earlier if the entry has never been used.
*/
Date getLastAccessTime();
/**
* Returns the date at which this entry was created
*/
Date getCreationTime();
/**
* Returns true if this entry is to be considered as expired at some point
*/
boolean getExpires();
/**
* Set true for the date returned by {@link #getExpiryTime()} to be considered an expiry time
* @see #setExpiryTime(Date)
*/
void setExpires(boolean expires);
/**
* Returns a date at which the entry should be considered to have expired, if {@link #getExpires()} is true -
* otherwise returns an arbitrary date.
*/
Date getExpiryTime();
/**
* Sets the expiry date of this element.
* @throws IllegalArgumentException if expiryTime is null.
* @see org.linguafranca.pwdb.Entry#setExpires(boolean)
*/
void setExpiryTime(Date expiryTime) throws IllegalArgumentException;
/**
* Returns the date that the entry was last modified
*
* Implementations SHOULD set this to the creation date or earlier if the entry has never been used.
*/
Date getLastModificationTime();
}