-
Notifications
You must be signed in to change notification settings - Fork 5
/
GraphicSource.java
104 lines (97 loc) · 5.44 KB
/
GraphicSource.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
/*
* © 2021. TU Dortmund University,
* Institute of Energy Systems, Energy Efficiency and Energy Economics,
* Research group Distribution grid planning and operation
*/
package edu.ie3.datamodel.io.source;
import edu.ie3.datamodel.exceptions.SourceException;
import edu.ie3.datamodel.models.input.NodeInput;
import edu.ie3.datamodel.models.input.connector.LineInput;
import edu.ie3.datamodel.models.input.container.GraphicElements;
import edu.ie3.datamodel.models.input.graphics.LineGraphicInput;
import edu.ie3.datamodel.models.input.graphics.NodeGraphicInput;
import java.util.Set;
/**
* Interface that provides the capability to build entities of type {@link
* edu.ie3.datamodel.models.input.graphics.GraphicInput} from different data sources e.g. .csv files
* or databases
*
* @version 0.1
* @since 08.04.20
*/
public interface GraphicSource extends DataSource {
/**
* Should return either a consistent instance of {@link GraphicElements} or throw a {@link
* SourceException}. The decision to throw a {@link SourceException} instead of returning the
* incomplete {@link GraphicElements} instance is motivated by the fact, that a {@link
* GraphicElements} is a container instance that depends on several other entities. Without being
* complete, it is useless for further processing. Hence, whenever at least one entity {@link
* GraphicElements} depends on cannot be provided, {@link SourceException} should be thrown. The
* thrown exception exception should provide enough information to debug the error and fix the
* persistent data that has been failed to processed.
*
* <p>Furthermore, it is expected, that the specific implementation of this method ensures not
* only the completeness of the resulting {@link GraphicElements} instance, but also its validity
* e.g. in the sense that not duplicate UUIDs exist within all entities contained in the returning
* instance.
*
* @return either a valid, complete {@link GraphicElements} or throws a {@link SourceException}
*/
GraphicElements getGraphicElements() throws SourceException;
/**
* Returns a set of {@link NodeGraphicInput} instances. This set has to be unique in the sense of
* object uniqueness but also in the sense of {@link java.util.UUID} uniqueness of the provided
* {@link NodeGraphicInput} which has to be checked manually, as {@link
* NodeGraphicInput#equals(Object)} is NOT restricted on the uuid of {@link NodeGraphicInput}.
*
* @return a set of object and uuid unique {@link NodeGraphicInput} entities
*/
Set<NodeGraphicInput> getNodeGraphicInput() throws SourceException;
/**
* Returns a set of {@link NodeGraphicInput} instances. This set has to be unique in the sense of
* object uniqueness but also in the sense of {@link java.util.UUID} uniqueness of the provided
* {@link NodeGraphicInput} which has to be checked manually, as {@link
* NodeGraphicInput#equals(Object)} is NOT restricted on the uuid of {@link NodeGraphicInput}.
*
* <p>In contrast to {@link #getNodeGraphicInput} this interface provides the ability to pass in
* an already existing set of {@link NodeInput} entities, the {@link NodeGraphicInput} instances
* depend on. Doing so, already loaded nodes can be recycled to improve performance and prevent
* unnecessary loading operations.
*
* <p>If something fails during the creation process it's up to the concrete implementation of an
* empty set or a set with all entities that has been able to be build is returned.
*
* @param nodes a set of object and uuid unique nodes that should be used for the returning
* instances
* @return a set of object and uuid unique {@link NodeGraphicInput} entities
*/
Set<NodeGraphicInput> getNodeGraphicInput(Set<NodeInput> nodes) throws SourceException;
/**
* Returns a set of {@link LineGraphicInput} instances. This set has to be unique in the sense of
* object uniqueness but also in the sense of {@link java.util.UUID} uniqueness of the provided
* {@link LineGraphicInput} which has to be checked manually, as {@link
* LineGraphicInput#equals(Object)} is NOT restricted on the uuid of {@link LineGraphicInput}.
*
* @return a set of object and uuid unique {@link LineGraphicInput} entities
*/
Set<LineGraphicInput> getLineGraphicInput() throws SourceException;
/**
* Returns a set of {@link LineGraphicInput} instances. This set has to be unique in the sense of
* object uniqueness but also in the sense of {@link java.util.UUID} uniqueness of the provided
* {@link LineGraphicInput} which has to be checked manually, as {@link
* LineGraphicInput#equals(Object)} is NOT restricted on the uuid of {@link LineGraphicInput}.
*
* <p>In contrast to {@link #getLineGraphicInput} this interface provides the ability to pass in
* an already existing set of {@link LineInput} entities, the {@link LineGraphicInput} instances
* depend on. Doing so, already loaded nodes can be recycled to improve performance and prevent
* unnecessary loading operations.
*
* <p>If something fails during the creation process it's up to the concrete implementation of an
* empty set or a set with all entities that has been able to be build is returned.
*
* @param lines a set of object and uuid unique lines that should be used for the returning
* instances
* @return a set of object and uuid unique {@link LineGraphicInput} entities
*/
Set<LineGraphicInput> getLineGraphicInput(Set<LineInput> lines) throws SourceException;
}