From 17c8f26233b5c8248dc6bbdc427bd67420b63a71 Mon Sep 17 00:00:00 2001 From: Hallvard Traetteberg <hal@ntnu.no> Date: Wed, 4 Apr 2018 08:39:35 +0200 Subject: [PATCH] Cleanups and documentation. --- tdt4140-gr1800/app.core/README.md | 2 +- .../app.core/doc/document-storage.md | 17 ++++ ...based-storage.png => document-storage.png} | Bin .../app.core/doc/location-based-storage.md | 5 -- .../tdt4140/gr1800/app/core/GeoLocated.java | 32 ++++++- .../tdt4140/gr1800/app/core/GeoLocation.java | 29 ++++--- .../java/tdt4140/gr1800/app/core/Tagged.java | 2 +- .../java/tdt4140/gr1800/app/core/Tags.java | 45 ++++++---- .../gr1800/app/core/TimedTaggedImpl.java | 30 ++++--- .../app/doc/AbstractDocumentStorageImpl.java | 80 ++++++++++++------ .../gr1800/app/doc/IDocumentImporter.java | 11 +++ .../gr1800/app/doc/IDocumentListener.java | 15 +++- .../gr1800/app/doc/IDocumentLoader.java | 13 +++ .../gr1800/app/doc/IDocumentSaver.java | 14 +++ .../gr1800/app/doc/IDocumentStorage.java | 41 +++++++++ .../app/doc/IDocumentStorageListener.java | 12 +++ 16 files changed, 269 insertions(+), 79 deletions(-) create mode 100644 tdt4140-gr1800/app.core/doc/document-storage.md rename tdt4140-gr1800/app.core/doc/{location-based-storage.png => document-storage.png} (100%) delete mode 100644 tdt4140-gr1800/app.core/doc/location-based-storage.md diff --git a/tdt4140-gr1800/app.core/README.md b/tdt4140-gr1800/app.core/README.md index f292c7a..41ba674 100644 --- a/tdt4140-gr1800/app.core/README.md +++ b/tdt4140-gr1800/app.core/README.md @@ -3,4 +3,4 @@ * [Domain model](doc/domain-model.md) * [DB-based persistence](doc/db-persistence.md) * [JSON-based serialization](doc/json-persistence.md) -* [Location-based storage](doc/location-based-storage.md) +* [Document storage](doc/document-storage.md) diff --git a/tdt4140-gr1800/app.core/doc/document-storage.md b/tdt4140-gr1800/app.core/doc/document-storage.md new file mode 100644 index 0000000..36d87c6 --- /dev/null +++ b/tdt4140-gr1800/app.core/doc/document-storage.md @@ -0,0 +1,17 @@ +# Document-based storage of domain data + +By *document-based storage* we mean a storage model where a *document* containing domain data is loaded/saved *as a whole*, from/to some explicitly provided *location*. This storage model is typical for document-centric desktop apps with a **File** menu containing actions like **open**, **save**, **save-as** etc. The interfaces and implementation classes described here are designed to support such **File** menu actions. A class diagram of the main classes related to location-based storage is shown below. + +* **IDocumentStorage**: An interface with the methods necessary for supporting the standard **File** menu actions. The interface is parameterized with the type used for representing the location to load from or save to. The class representing the document (domain data container) is implicit in the implementation of this interface. The interface includes methods for getting and setting the location and creating, opening and saving the (current) document. +* **IDocumentImporter**: An interface with a method for importing domain data from a location. The interface is parameterized with the location type. The main use is supporting an **import** action in a **File** menu. + +* **IDocumentLoader**: An interface with a method for loading and returning a document (domain data container) from an **InputStream**. The interface is parameterized with the document type. This allows various ways of loading or importing domain data, with different sources and formats. +* **IDocumentSaver**: An interface with a method for saving a document (domain data container) to a location. The interface is parameterized with the document and location types. This allows various ways of saving or exporting domain data, to different locations and formats. +* **IDocumentPersistence**: Combination of **IDocumentLoader** and **IDocumentSaver**. + +* **IDocumentStorageListener**: Listener interface for the location of the (current) document of an IDocumentStorage, e.g. when a **save-as** action is performed. +* **IDocumentListener**: Listener interface for the contents of the (current) document of an IDocumentStorage, e.g. when a document is created, opened or imported. + +* **AbstractDocumentStorageImpl**: Incomplete implementation of **IDocumentStorage**, to simplify implementing ones for specific document and location types. The main missing methods are for getting and setting the current document, creating an empty one and creating an **InputStream** from a location. + +<img src="location-based-storage.png" alt="Location-based persistence" style="width: 800px;"/> diff --git a/tdt4140-gr1800/app.core/doc/location-based-storage.png b/tdt4140-gr1800/app.core/doc/document-storage.png similarity index 100% rename from tdt4140-gr1800/app.core/doc/location-based-storage.png rename to tdt4140-gr1800/app.core/doc/document-storage.png diff --git a/tdt4140-gr1800/app.core/doc/location-based-storage.md b/tdt4140-gr1800/app.core/doc/location-based-storage.md deleted file mode 100644 index ce14abc..0000000 --- a/tdt4140-gr1800/app.core/doc/location-based-storage.md +++ /dev/null @@ -1,5 +0,0 @@ -# Location-based storage of domain data - -A class diagram of the main classes related to location-based storage is shown below. - -<img src="location-based-storage.png" alt="Location-based persistence" style="width: 800px;"/> diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocated.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocated.java index e4ea1ba..3bacd14 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocated.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocated.java @@ -1,19 +1,45 @@ package tdt4140.gr1800.app.core; +/** + * Interface for geo-located data, i.e. classes that can return a corresponding LatLong object. + * @author hal + * + */ public interface GeoLocated { + /** + * @return the corresponding LatLong object + */ public LatLong getLatLong(); - + + /** + * @return the corresponding latitude + */ default double getLatitude() { return getLatLong().latitude; } + + /** + * @return the corresponding longitude + */ default double getLongitude() { return getLatLong().longitude; } - default boolean equalsLatLong(GeoLocated geoLoc) { + + /** + * Checks that the latitudes and longitudes are the same + * @param geoLoc + * @return true if the latitudes and longitudes are the same, false otherwise + */ + default boolean equalsLatLong(final GeoLocated geoLoc) { return getLatitude() == geoLoc.getLatitude() && getLongitude() == geoLoc.getLongitude(); } - default double distance(GeoLocated geoLoc) { + + /** + * @param geoLoc + * @return the distance between the LatLong of this GeoLocated and the one provided + */ + default double distance(final GeoLocated geoLoc) { return getLatLong().distance(geoLoc.getLatLong()); } } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocation.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocation.java index 82075bc..00e8484 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocation.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/GeoLocation.java @@ -1,42 +1,49 @@ package tdt4140.gr1800.app.core; +/** + * Main implementation of GeoLocated. Combines a LatLong and elevation with generic values + * like name, description, time (implements Timed) and tags (implements Tagged). + * @author hal + * + */ public class GeoLocation extends TimedTaggedImpl implements GeoLocated, Timed, Tagged { private LatLong latLong; + @Override public LatLong getLatLong() { return latLong; } - public void setLatLong(LatLong latLong) { + public void setLatLong(final LatLong latLong) { this.latLong = latLong; } private int elevation; - + public int getElevation() { return elevation; } - - public void setElevation(int elevation) { + + public void setElevation(final int elevation) { this.elevation = elevation; } - + private String name, description; - + public String getName() { return name; } - - public void setName(String name) { + + public void setName(final String name) { this.name = name; } - + public String getDescription() { return description; } - - public void setDescription(String description) { + + public void setDescription(final String description) { this.description = description; } } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tagged.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tagged.java index ddd1ae7..c188fe0 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tagged.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tagged.java @@ -5,6 +5,6 @@ public interface Tagged { public String[] getTags(); public String getTags(String prefix, String separator, String suffix); public void setTags(String... tags); - public void addTags(String... tags); + public void addTags(String... tags); public void removeTags(String... tags); } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tags.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tags.java index 58c01a3..a719070 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tags.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/Tags.java @@ -3,33 +3,40 @@ package tdt4140.gr1800.app.core; import java.util.ArrayList; import java.util.Arrays; import java.util.Collection; +import java.util.Collections; +import java.util.Iterator; -public class Tags implements Tagged { +public class Tags implements Tagged, Iterable<String> { private Collection<String> tags = null; - public Tags(String... tags) { + @Override + public Iterator<String> iterator() { + return (tags != null ? tags.iterator() : Collections.<String>emptyList().iterator()); + } + + public Tags(final String... tags) { setTags(tags); } - public Tags(Tagged tags) { + public Tags(final Tagged tags) { setTags(tags.getTags()); } - public static Tags valueOf(String tags) { + public static Tags valueOf(final String tags) { return valueOf(tags, ","); } - public static Tags valueOf(String tags, String separator) { + public static Tags valueOf(final String tags, final String separator) { return new Tags(tags.split(separator)); } public int getTagCount() { return (tags == null ? 0 : tags.size()); } - + @Override - public boolean hasTags(String... tags) { + public boolean hasTags(final String... tags) { return (tags.length == 0 || (this.tags != null && this.tags.containsAll(Arrays.asList(tags)))); } @@ -39,15 +46,15 @@ public class Tags implements Tagged { public String[] getTags() { return (tags != null ? tags.toArray(new String[tags.size()]) : EMPTY_STRINGS); } - + @Override - public String getTags(String prefix, String separator, String suffix) { - StringBuilder buffer = new StringBuilder(); + public String getTags(final String prefix, final String separator, final String suffix) { + final StringBuilder buffer = new StringBuilder(); append(buffer, prefix); int tagNum = 0; - for (String tag : tags) { + for (final String tag : tags) { if (tagNum > 0 && separator != null) { - buffer.append(separator); + buffer.append(separator); } buffer.append(tag); tagNum++; @@ -56,20 +63,21 @@ public class Tags implements Tagged { return buffer.toString(); } - static StringBuilder append(StringBuilder buffer, String s) { + static StringBuilder append(final StringBuilder buffer, final String s) { if (s != null) { buffer.append(s); } return buffer; } - + @Override - public void setTags(String... tags) { + public void setTags(final String... tags) { this.tags = new ArrayList<>(); addTags(tags); } - public void addTags(String... tags) { + @Override + public void addTags(final String... tags) { if (this.tags == null && tags != null && tags.length > 0) { this.tags = new ArrayList<>(); } @@ -79,8 +87,9 @@ public class Tags implements Tagged { } } } - - public void removeTags(String... tags) { + + @Override + public void removeTags(final String... tags) { if (this.tags != null) { this.tags.removeAll(Arrays.asList(tags)); } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/TimedTaggedImpl.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/TimedTaggedImpl.java index c8ccbdf..f9d13d9 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/TimedTaggedImpl.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/core/TimedTaggedImpl.java @@ -1,32 +1,32 @@ package tdt4140.gr1800.app.core; public class TimedTaggedImpl extends TimedImpl implements Tagged { - + private Tags tags = null; public TimedTaggedImpl() { } - public TimedTaggedImpl(Tagged tags) { + public TimedTaggedImpl(final Tagged tags) { setTags(tags.getTags()); } - private static TimedTaggedImpl valueOf(Tags tags) { - TimedTaggedImpl timedTags = new TimedTaggedImpl(); + private static TimedTaggedImpl valueOf(final Tags tags) { + final TimedTaggedImpl timedTags = new TimedTaggedImpl(); timedTags.tags = tags; return timedTags; } - public static TimedTaggedImpl valueOf(String tags) { + public static TimedTaggedImpl valueOf(final String tags) { return valueOf(Tags.valueOf(tags)); } - - public static TimedTaggedImpl valueOf(String tags, String separator) { + + public static TimedTaggedImpl valueOf(final String tags, final String separator) { return valueOf(Tags.valueOf(tags, separator)); } @Override - public boolean hasTags(String... tags) { + public boolean hasTags(final String... tags) { return this.tags != null && this.tags.hasTags(tags); } @@ -34,25 +34,27 @@ public class TimedTaggedImpl extends TimedImpl implements Tagged { public String[] getTags() { return (tags != null ? tags.getTags() : Tags.EMPTY_STRINGS); } - + @Override - public String getTags(String prefix, String separator, String suffix) { + public String getTags(final String prefix, final String separator, final String suffix) { return (tags != null ? tags.getTags(prefix, separator, suffix) : Tags.append(Tags.append(new StringBuilder(), prefix), suffix).toString()); } @Override - public void setTags(String... tags) { + public void setTags(final String... tags) { this.tags = (tags != null && tags.length > 0 ? new Tags(tags) : null); } - public void addTags(String... tags) { + @Override + public void addTags(final String... tags) { if (this.tags == null) { this.tags = new Tags(); } this.tags.addTags(tags); } - - public void removeTags(String... tags) { + + @Override + public void removeTags(final String... tags) { if (this.tags != null) { this.tags.removeTags(tags); if (this.tags.getTagCount() == 0) { diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/AbstractDocumentStorageImpl.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/AbstractDocumentStorageImpl.java index 0203ad7..4aa99d9 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/AbstractDocumentStorageImpl.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/AbstractDocumentStorageImpl.java @@ -5,6 +5,15 @@ import java.io.InputStream; import java.util.ArrayList; import java.util.Collection; +/** + * Incomplete implementation of **IDocumentStorage**, to simplify implementing ones for specific document and location types. + * The main missing methods are for getting and setting the current document, creating an empty one and + * creating an **InputStream** from a location. + * @author hal + * + * @param <D> the document type + * @param <L> the location type + */ public abstract class AbstractDocumentStorageImpl<D, L> implements IDocumentStorage<L>, IDocumentPersistence<D, L> { private L documentLocation; @@ -15,60 +24,81 @@ public abstract class AbstractDocumentStorageImpl<D, L> implements IDocumentStor } @Override - public void setDocumentLocation(L documentLocation) { - L oldDocumentLocation = this.documentLocation; + public void setDocumentLocation(final L documentLocation) { + final L oldDocumentLocation = this.documentLocation; this.documentLocation = documentLocation; fireDocumentLocationChanged(oldDocumentLocation); } - protected void setDocumentAndLocation(D document, L documentLocation) { + protected void setDocumentAndLocation(final D document, final L documentLocation) { setDocument(document); setDocumentLocation(documentLocation); } + /** + * Returns the current document. + * @return the current document + */ protected abstract D getDocument(); + + /** + * Sets the current document + * @param document the new document + */ protected abstract void setDocument(D document); // - - private Collection<IDocumentStorageListener<L>> documentListeners = new ArrayList<IDocumentStorageListener<L>>(); - - public void addDocumentStorageListener(IDocumentStorageListener<L> documentStorageListener) { + + private final Collection<IDocumentStorageListener<L>> documentListeners = new ArrayList<IDocumentStorageListener<L>>(); + + @Override + public void addDocumentStorageListener(final IDocumentStorageListener<L> documentStorageListener) { documentListeners.add(documentStorageListener); } - public void removeDocumentStorageListener(IDocumentStorageListener<L> documentStorageListener) { + @Override + public void removeDocumentStorageListener(final IDocumentStorageListener<L> documentStorageListener) { documentListeners.remove(documentStorageListener); } - - protected void fireDocumentLocationChanged(L oldDocumentLocation) { - for (IDocumentStorageListener<L> documentStorageListener : documentListeners) { + + protected void fireDocumentLocationChanged(final L oldDocumentLocation) { + for (final IDocumentStorageListener<L> documentStorageListener : documentListeners) { documentStorageListener.documentLocationChanged(documentLocation, oldDocumentLocation); } } - protected void fireDocumentChanged(D oldDocument) { - for (IDocumentStorageListener<L> documentListener : documentListeners) { + protected void fireDocumentChanged(final D oldDocument) { + for (final IDocumentStorageListener<L> documentListener : documentListeners) { if (documentListener instanceof IDocumentListener) { ((IDocumentListener<D, L>) documentListener).documentChanged(getDocument(), oldDocument); } } } - + + /** + * Creates a new and empty document. + * @return + */ protected abstract D createDocument(); - + @Override public void newDocument() { setDocumentAndLocation(createDocument(), null); } - - protected abstract InputStream toInputStream(L storage) throws IOException; + + /** + * Creates an ImportStream from a location + * @param location + * @return + * @throws IOException + */ + protected abstract InputStream toInputStream(L location) throws IOException; @Override - public void openDocument(L storage) throws IOException { + public void openDocument(final L storage) throws IOException { try (InputStream input = toInputStream(storage)){ setDocumentAndLocation(loadDocument(input), storage); - } catch (Exception e) { + } catch (final Exception e) { throw new IOException(e); } } @@ -77,23 +107,23 @@ public abstract class AbstractDocumentStorageImpl<D, L> implements IDocumentStor public void saveDocument() throws IOException { try { saveDocument(getDocument(), getDocumentLocation()); - } catch (Exception e) { + } catch (final Exception e) { throw new IOException(e); } } - public void saveDocumentAs(L documentLocation) throws IOException { - L oldDocumentLocation = getDocumentLocation(); + public void saveDocumentAs(final L documentLocation) throws IOException { + final L oldDocumentLocation = getDocumentLocation(); setDocumentLocation(documentLocation); try { saveDocument(); - } catch (IOException e) { + } catch (final IOException e) { setDocumentLocation(oldDocumentLocation); throw e; } } - - public void saveCopyAs(L documentLocation) throws Exception { + + public void saveCopyAs(final L documentLocation) throws Exception { saveDocument(getDocument(), documentLocation); } } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentImporter.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentImporter.java index 2b9327b..cf1bc9b 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentImporter.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentImporter.java @@ -3,6 +3,17 @@ package tdt4140.gr1800.app.doc; import java.io.IOException; import java.io.InputStream; +/** + * An interface with a method for importing domain data from a location. + * The main use is supporting an **import** action in a **File** menu. + * @author hal + * + */ public interface IDocumentImporter { + /** + * Loads a document from the input stream and sets it as the current document. + * @param inputStream + * @throws IOException + */ public void importDocument(InputStream inputStream) throws IOException; } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentListener.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentListener.java index 62b8ce2..855cc9a 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentListener.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentListener.java @@ -1,5 +1,18 @@ package tdt4140.gr1800.app.doc; -public interface IDocumentListener<D, L> extends IDocumentStorageListener<L>{ +/** + * Listener interface for the (contents of) the (current) document of an IDocumentStorage, e.g. + * when an **open** action is performed. + * @author hal + * + * @param <D> the document type + * @param <L> the location type + */ +public interface IDocumentListener<D, L> extends IDocumentStorageListener<L> { + /** + * Notifies that the current document has changed. + * @param document the new document + * @param oldDocument the previous document + */ public void documentChanged(D document, D oldDocument); } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentLoader.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentLoader.java index 8c719fe..083b698 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentLoader.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentLoader.java @@ -2,6 +2,19 @@ package tdt4140.gr1800.app.doc; import java.io.InputStream; +/** + * An interface with a method for loading and returning a document (domain data container) from an InputStream. + * This allows various ways of loading or importing domain data, with different sources and formats. + * @author hal + * + * @param <D> the document type + */ public interface IDocumentLoader<D> { + /** + * Loads and returns a new document from an InputStream + * @param inputStream + * @return + * @throws Exception + */ public D loadDocument(InputStream inputStream) throws Exception; } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentSaver.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentSaver.java index b9a5d92..af4b00f 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentSaver.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentSaver.java @@ -1,5 +1,19 @@ package tdt4140.gr1800.app.doc; +/** + * An interface with a method for saving a document (domain data container) to a location. + * This allows various ways of saving or exporting domain data, to different locations and formats. + * @author hal + * + * @param <D> the document type + * @param <L> the location type + */ public interface IDocumentSaver<D, L> { + /** + * Saves the provided document to the provided location + * @param document + * @param documentLocation + * @throws Exception + */ public void saveDocument(D document, L documentLocation) throws Exception; } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorage.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorage.java index 1f30c37..29ad777 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorage.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorage.java @@ -3,16 +3,57 @@ package tdt4140.gr1800.app.doc; import java.io.IOException; import java.util.Collection; +/** + * An interface with the methods necessary for supporting the standard File menu actions. + * The class representing the document (domain data container) is implicit in the implementation of this interface. + * The interface includes methods for getting and setting the location and creating, opening and saving the (current) document. + * @author hal + * + * @param <L> The type of the location, typically java.io.File. + */ public interface IDocumentStorage<L> { + /** + * Returns the current location (of the current document). + * @return the current location + */ public L getDocumentLocation(); + + /** + * Sets the current location (of the current document), can be used by a save-as action. + * @param documentLocation + */ public void setDocumentLocation(L documentLocation); + /** + * Adds an IDocumentStorageListener that will be notified when the current location changes. + * @param documentStorageListener + */ + public void addDocumentStorageListener(IDocumentStorageListener<L> documentStorageListener); + /** + * Removes an IDocumentStorageListener. + * @param documentStorageListener + */ public void removeDocumentStorageListener(IDocumentStorageListener<L> documentStorageListener); + /** + * Creates a new documents and sets it as the current one, can be used by a new action. + */ public void newDocument(); + + /** + * Loads a documents from the provided location and sets it as the current one, can be used by an open action. + */ public void openDocument(L documentLocation) throws IOException; + + /** + * Saves the current document (to the current location), can be used by a save action. + */ public void saveDocument() throws IOException; + /** + * Returns the set of IDocumentImporters, can be used by an import action. + * @return + */ public Collection<IDocumentImporter> getDocumentImporters(); } diff --git a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorageListener.java b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorageListener.java index 1a21cdc..12eae7b 100644 --- a/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorageListener.java +++ b/tdt4140-gr1800/app.core/src/main/java/tdt4140/gr1800/app/doc/IDocumentStorageListener.java @@ -1,5 +1,17 @@ package tdt4140.gr1800.app.doc; +/** + * Listener interface for the (current) location of the (current) document of an IDocumentStorage, e.g. + * when a **save-as** action is performed. + * @author hal + * + * @param <L> + */ public interface IDocumentStorageListener<L> { + /** + * Notifies that the current document location has changed. + * @param documentLocation the new document location + * @param oldDocumentLocation the previous document location + */ public void documentLocationChanged(L documentLocation, L oldDocumentLocation); } -- GitLab