diff --git a/tdt4140-gr1800/app.core/README.md b/tdt4140-gr1800/app.core/README.md
index f292c7aced46833d99b0b6cbaa9be2e4b5a44fd5..41ba6740471fd6ec0067d2e6be98ef86f314fbee 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 0000000000000000000000000000000000000000..36d87c6902e05045be40ffdf46c10a25357f5da7
--- /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 ce14abc190abd8681d4aa29f2ea61688ce427a04..0000000000000000000000000000000000000000
--- 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 e4ea1bae63c6531b4881fdc9bbb802bb461207d5..3bacd14000a0c68d5f6c2c2eb2d254bbe8988a62 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 82075bc204491feeee0680d45f1a99c13dc93b1e..00e84848548c327a93119e36999cd6eed64ff15a 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 ddd1ae71fddcde5b0fc54afc4a7610304f903527..c188fe0fc06ca6e223861d7b2e420da122480a61 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 58c01a3271f0a8b92cb619ee5b726f10cfe196e4..a71907023681c06f146e5bcbc2fab3423a7a8393 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 c8ccbdf4228e7d668c13c5d84de1920dd29244c4..f9d13d997bcacfc559cf9e84ef3e85f90333885b 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 0203ad70ed35a06fddf891bacd543158989b31f6..4aa99d96a9f7ce6e3e5affcec0b82ec2b6db1bdb 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 2b9327b74773afe7409a67f0048ca17a7820aa7f..cf1bc9b85704a9f013e999db51835341e0a481af 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 62b8ce211c1ca51449ef015efba9afabff903737..855cc9a7f8835f0c4d365b710988bc02649f8a26 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 8c719fe9720e03adc8ca65d2555f2babc07e66db..083b6983b246103c63258afcb6db54817cc592d8 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 b9a5d9264be304554845f6c5592c5aec9a79d741..af4b00f150ef91d5f2f6914b5a345f7487169601 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 1f30c37808e5eaaab146f93a2d931af16683b03a..29ad777aaea21594b849caa267b57dbb5051d148 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 1a21cdc63a83391fae9c7d1dd13abcce47e807d1..12eae7b4aafe722b17c616841e4e553dafab53d4 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);
}