Skip to content

Commit 62d34bb

Browse files
bischoffzbischoffz
committed
update javadoc
1 parent ca05c09 commit 62d34bb

File tree

5 files changed

+266
-129
lines changed

5 files changed

+266
-129
lines changed

‎core/src/main/java/gov/hhs/aspr/ms/taskit/core/engine/ITaskitEngine.java

Lines changed: 119 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,144 @@
33
import java.io.IOException;
44
import java.nio.file.Path;
55

6+
import gov.hhs.aspr.ms.taskit.core.translation.TranslationSpec;
7+
8+
/**
9+
* Interface for a {@link TaskitEngine} that applies to TaskitEngine and any
10+
* derivatives thereof
11+
*/
612
public interface ITaskitEngine {
713

14+
/**
15+
* @return the {@link TaskitEngine} associated with the given TaskitEngine.
16+
* <p>
17+
* Note that for {@link TaskitEngine} this method returns itself.
18+
*/
819
public TaskitEngine getTaskitEngine();
920

21+
/**
22+
* @return the {@link TaskitEngineId} associated with the TaskitEngine
23+
*/
1024
public TaskitEngineId getTaskitEngineId();
1125

26+
/**
27+
* Writes the object to the file referenced by the Path
28+
*
29+
* @param <O> the type of the object to write
30+
* @param path the path of the file to write to
31+
* @param object the object to write
32+
* @throws IOException if there is an issue writing the file
33+
*/
1234
public <O> void write(Path path, O object) throws IOException;
1335

36+
/**
37+
* Translates the object and then writes the translated object to the file
38+
* reference by the Path
39+
*
40+
* @param <O> the type of the object to write
41+
* @param path the path of the file to write to
42+
* @param object the object to write
43+
* @throws IOException if there is an issue writing the file
44+
*/
1445
public <O> void translateAndWrite(Path path, O object) throws IOException;
1546

16-
public <OC, O extends OC> void translateAndWrite(Path path, O object, Class<OC> classRef)
47+
/**
48+
* Translates the object as the provided class and then writes the translated
49+
* object to the file referenced by the Path
50+
* <p>
51+
* The type params ensure that the object can be written as the provided class
52+
*
53+
* @param <C> the type to translate the object as
54+
* @param <O> the type of the object
55+
* @param path the path of the file to write to
56+
* @param object the object to write
57+
* @param classRef the class to translate the object as
58+
* @throws IOException if there is an issue writing the file
59+
*/
60+
public <C, O extends C> void translateAndWrite(Path path, O object, Class<C> classRef)
1761
throws IOException;
1862

63+
/**
64+
* Reads the given path into the provided class type
65+
*
66+
* @param <I> the input type
67+
* @param path the path of the file to read
68+
* @param classRef the class to read the file as
69+
* @return the resulting object from reading the file as the class
70+
* @throws IOException if there is an issue reading the file
71+
*/
1972
public <I> I read(Path path, Class<I> classRef) throws IOException;
2073

74+
/**
75+
* Reads the given path into the provided class type and then translates it to
76+
* the corresponding type associated with the input type
77+
*
78+
* @param <T> the translated type
79+
* @param <I> the input type
80+
* @param path the path of the file to read
81+
* @param classRef the class to read the file as
82+
* @return the resulting translated read in object
83+
* @throws IOException if there is an issue reading the file
84+
*/
2185
public <T, I> T readAndTranslate(Path path, Class<I> classRef) throws IOException;
2286

87+
/**
88+
* Given an object, uses the class of the object to obtain the translationSpec
89+
* and then calls {@link TranslationSpec#translate(Object)} to translate the
90+
* object
91+
* <p>
92+
* this conversion method will be used approx ~90% of the time
93+
* </p>
94+
*
95+
* @param <T> the translated type
96+
* @param object the object to translate
97+
* @return the translated object
98+
*/
2399
public <T> T translateObject(Object object);
24100

101+
/**
102+
* Given an object, uses the given classRef to obtain the
103+
* translationSpec and then calls {@link TranslationSpec#translate(Object)}
104+
* <p>
105+
* This method call is safe in the sense that the type parameters ensure that
106+
* the passed in object is actually a child of the passed in classRef
107+
* </p>
108+
* <p>
109+
* this conversion method will be used approx ~7% of the time
110+
* </p>
111+
*
112+
* @param <T> the translated type
113+
* @param <O> the type of the object
114+
* @param <C> the type to translate the object as
115+
* @param object the object to translate
116+
* @param classRef the classRef of the type to translate the object as
117+
* @return the translated object
118+
*/
25119
public <T, O extends C, C> T translateObjectAsClassSafe(O object, Class<C> classRef);
26120

121+
/**
122+
* Given an object, uses the given classRef to obtain the
123+
* translationSpec and then calls {@link TranslationSpec#translate(Object)}
124+
* <p>
125+
* There is no type safety with this method unlike the
126+
* {@link ITaskitEngine#translateObjectAsClassSafe(Object, Class)} method.
127+
* Therefore it is on the caller of this method to ensure that the given object
128+
* can be translated using the given classRef.
129+
* <p>
130+
* A conventional use case for this would be when you want to wrap an object
131+
* into another object type where there is no correlation between the wrapping
132+
* object and the object being wrapped.
133+
* </p>
134+
* <p>
135+
* this conversion method will be used approx ~3% of the time
136+
* </p>
137+
*
138+
* @param <T> the corresponding type
139+
* @param <O> the type of the object
140+
* @param <C> the type to translate the object as
141+
* @param object the object to translate
142+
* @param classRef the classRef of the type to translate the object as
143+
* @return the translated object
144+
*/
27145
public <T, O, C> T translateObjectAsClassUnsafe(O object, Class<C> classRef);
28146
}

‎core/src/main/java/gov/hhs/aspr/ms/taskit/core/engine/ITaskitEngineBuilder.java

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,30 @@
33
import gov.hhs.aspr.ms.taskit.core.translation.TranslationSpec;
44
import gov.hhs.aspr.ms.taskit.core.translation.Translator;
55

6+
/**
7+
* Interface for TaskitEngine Builders
8+
*/
69
public interface ITaskitEngineBuilder {
10+
/**
11+
* @return the built TaskitEngine
12+
*/
713
public ITaskitEngine build();
814

15+
/**
16+
* Adds the given {@link TranslationSpec} to the TaskitEngine
17+
*
18+
* @param <I> the input type
19+
* @param <A> the app type
20+
* @param translationSpec the translationSpec to add
21+
* @return the builder instance
22+
*/
923
public <I, A> ITaskitEngineBuilder addTranslationSpec(TranslationSpec<I, A> translationSpec);
1024

25+
/**
26+
* Adds the given {@link Translator} to the TaskitEngine
27+
*
28+
* @param translator the translator to add
29+
* @return the builder instance
30+
*/
1131
public ITaskitEngineBuilder addTranslator(Translator translator);
1232
}

‎core/src/main/java/gov/hhs/aspr/ms/taskit/core/engine/TaskitCoreError.java

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
import gov.hhs.aspr.ms.util.errors.ContractError;
44

5+
/**
6+
* Errors that describe contract exceptions within Taskit
7+
*/
58
public enum TaskitCoreError implements ContractError {
69

710
CIRCULAR_TRANSLATOR_DEPENDENCIES("Circular translator dependencies: "),

0 commit comments

Comments
 (0)