From 7e73f08bea1d9f60d5fc90061f338aca7e5297bd Mon Sep 17 00:00:00 2001 From: anhefti Date: Thu, 18 Jun 2020 08:42:20 +0200 Subject: [PATCH] API documentation --- .../examconfig/ExamConfigurationService.java | 29 +++++ .../gui/service/i18n/PolyglotPageService.java | 104 +++++++++--------- .../servicelayer/exam/ExamAdminService.java | 4 + .../sebconfig/ExamConfigInitService.java | 9 ++ .../sebconfig/ExamConfigTemplateService.java | 32 ++++++ .../gbl/model/ModelObjectJSONGenerator.java | 39 +++++++ 6 files changed, 163 insertions(+), 54 deletions(-) create mode 100644 src/test/java/ch/ethz/seb/sebserver/gbl/model/ModelObjectJSONGenerator.java diff --git a/src/main/java/ch/ethz/seb/sebserver/gui/service/examconfig/ExamConfigurationService.java b/src/main/java/ch/ethz/seb/sebserver/gui/service/examconfig/ExamConfigurationService.java index 01646ec3..616bf7c2 100644 --- a/src/main/java/ch/ethz/seb/sebserver/gui/service/examconfig/ExamConfigurationService.java +++ b/src/main/java/ch/ethz/seb/sebserver/gui/service/examconfig/ExamConfigurationService.java @@ -28,6 +28,7 @@ import ch.ethz.seb.sebserver.gui.service.page.PageContext; import ch.ethz.seb.sebserver.gui.service.page.impl.PageAction; import ch.ethz.seb.sebserver.gui.widget.WidgetFactory; +/** Service offers functionality to compose and update SEB exam configuration properties page */ public interface ExamConfigurationService { String ATTRIBUTE_LABEL_LOC_TEXT_PREFIX = "sebserver.examconfig.props.label."; @@ -35,20 +36,48 @@ public interface ExamConfigurationService { String TOOL_TIP_SUFFIX = ".tooltip"; String TABLE_ROW_TITLE_SUFFIX = ".row.title"; + /** Get the WidgetFactory service + * + * @return the WidgetFactory service */ WidgetFactory getWidgetFactory(); InputFieldBuilder getInputFieldBuilder( ConfigurationAttribute attribute, Orientation orientation); + /** Get the attribute mapping of a specified template. + * + * @param templateId The template identifier + * @return Result refer to the attribute mapping or to an error if happened. */ Result getAttributes(Long templateId); + /** Get the attribute mapping for a specific template attribute with default orientation + * for fallback. + * + * @param attribute The template attribute instance. + * @param defaultOrientation the default orientation. + * @return Result refer to the attribute mapping or to an error if happened. */ Result getAttributes( final TemplateAttribute attribute, final Orientation defaultOrientation); + /** Get the list of defined views for a AttributeMapping. + * + * @param allAttributes AttributeMapping with all attributes + * @return list of defined views for a AttributeMapping */ List getViews(AttributeMapping allAttributes); + /** Create to ViewContext to compose a exam configuration property page, + * The ViewContext is the internal state of a exam configuration property page + * and is passed through all composers while composing the page. + * + * @param pageContext The original PageContext that holds the state of the overall page. + * @param configuration The configuration on which the exam configuration property page is based on. + * @param view The View of the context + * @param attributeMapping The attribute mapping if the properties page + * @param rows Number of rows supported for the view. + * @param readonly Indicates if the view shall be composed in read-only mode. + * @return ViewContext instance. */ ViewContext createViewContext( PageContext pageContext, Configuration configuration, diff --git a/src/main/java/ch/ethz/seb/sebserver/gui/service/i18n/PolyglotPageService.java b/src/main/java/ch/ethz/seb/sebserver/gui/service/i18n/PolyglotPageService.java index 33ee1d86..903503af 100644 --- a/src/main/java/ch/ethz/seb/sebserver/gui/service/i18n/PolyglotPageService.java +++ b/src/main/java/ch/ethz/seb/sebserver/gui/service/i18n/PolyglotPageService.java @@ -10,7 +10,17 @@ package ch.ethz.seb.sebserver.gui.service.i18n; import java.util.Locale; -import org.eclipse.swt.widgets.*; +import org.eclipse.swt.widgets.Button; +import org.eclipse.swt.widgets.Composite; +import org.eclipse.swt.widgets.Control; +import org.eclipse.swt.widgets.Group; +import org.eclipse.swt.widgets.Label; +import org.eclipse.swt.widgets.TabFolder; +import org.eclipse.swt.widgets.TabItem; +import org.eclipse.swt.widgets.Table; +import org.eclipse.swt.widgets.TableColumn; +import org.eclipse.swt.widgets.Tree; +import org.eclipse.swt.widgets.TreeItem; import ch.ethz.seb.sebserver.gui.service.page.PageContext; import ch.ethz.seb.sebserver.gui.widget.ImageUploadSelection; @@ -39,116 +49,102 @@ public interface PolyglotPageService { * @param locale the Locale to set */ void setPageLocale(Composite root, Locale locale); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param imageUpload the Control instance - * @param locTextKey the localized text key to inject - */ + * @param locTextKey the localized text key to inject */ void injectI18n(ImageUploadSelection imageUpload, LocTextKey locTextKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param label the Control instance - * @param locTextKey the localized text key to inject - */ + * @param locTextKey the localized text key to inject */ void injectI18n(Label label, LocTextKey locTextKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param label the Control instance * @param locTextKey the localized text key to inject - * @param locToolTipKey the localized text key for the tooltip to inject - */ + * @param locToolTipKey the localized text key for the tool-tip to inject */ void injectI18n(Label label, LocTextKey locTextKey, LocTextKey locToolTipKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param group the Control instance * @param locTextKey the localized text key to inject - * @param locTooltipKey the localized text key for the tooltip to inject - */ + * @param locTooltipKey the localized text key for the tool-tip to inject */ void injectI18n(Group group, LocTextKey locTextKey, LocTextKey locTooltipKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param button the Control instance - * @param locTextKey the localized text key to inject - */ + * @param locTextKey the localized text key to inject */ void injectI18n(Button button, LocTextKey locTextKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param button the Control instance * @param locTextKey the localized text key to inject - * @param locToolTipKey the localized text key for the tooltip to inject - */ + * @param locToolTipKey the localized text key for the tool-tip to inject */ void injectI18n(Button button, LocTextKey locTextKey, LocTextKey locToolTipKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * - * @param tree the Control instance - */ + * @param tree the Control instance */ void injectI18n(Tree tree); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param treeItem the Control instance - * @param locTextKey the localized text key to inject - */ + * @param locTextKey the localized text key to inject */ void injectI18n(TreeItem treeItem, LocTextKey locTextKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * - * @param table the Control instance - */ + * @param table the Control instance */ void injectI18n(Table table); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * - * @param tabFolder the Control instance - */ + * @param tabFolder the Control instance */ void injectI18n(TabFolder tabFolder); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param tableColumn the Control instance * @param locTextKey the localized text key to inject - * @param locTooltipKey the localized text key for the tooltip to inject - */ + * @param locTooltipKey the localized text key for the tooltip to inject */ void injectI18n(TableColumn tableColumn, LocTextKey locTextKey, LocTextKey locTooltipKey); - /** Used to inject a localised text within the given Control (Widget) that automatically gets changed on language - * change. + /** Used to inject a localized text within the given Control (Widget) that automatically gets changed on language + * change. * * @param tabItem the Control instance * @param locTextKey the localized text key to inject - * @param locTooltipKey the localized text key for the tooltip to inject - */ + * @param locTooltipKey the localized text key for the tool-tip to inject */ void injectI18n(TabItem tabItem, LocTextKey locTextKey, LocTextKey locTooltipKey); - /** Used to inject a localised tooltip text within the given Control (Widget) that automatically gets changed on + /** Used to inject a localized tool-tip text within the given Control (Widget) that automatically gets changed on * language change. * * @param control the Control instance - * @param locTooltipKey the localized text key for the tooltip to inject - */ + * @param locTooltipKey the localized text key for the tool-tip to inject */ void injectI18nTooltip(Control control, LocTextKey locTooltipKey); /** Used to create the page language selector if needed * - * @param composerCtx the PageContext - */ + * @param composerCtx the PageContext */ void createLanguageSelector(PageContext composerCtx); } \ No newline at end of file diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/exam/ExamAdminService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/exam/ExamAdminService.java index f325980d..9120ad1b 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/exam/ExamAdminService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/exam/ExamAdminService.java @@ -26,6 +26,10 @@ public interface ExamAdminService { * @return the Exam */ Result applyAdditionalSEBRestrictions(Exam exam); + /** Indicates wether a specific exam is been restricted with SEB restriction feature on the LMS or not. + * + * @param exam The exam instance + * @return Result refer to the restriction flag or to an error when happened */ Result isRestricted(Exam exam); } diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigInitService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigInitService.java index 88f8b1fc..9e8a66a0 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigInitService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigInitService.java @@ -14,8 +14,17 @@ import java.util.function.Function; import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationAttribute; import ch.ethz.seb.sebserver.gbl.model.sebconfig.ConfigurationValue; +/** Service to support and maintain initial default values for SEB exam configurations */ public interface ExamConfigInitService { + /** Use this to get all additinal initial default values for a newly created SEB exam configuration + * that are configured with the SEB Server configuration on SEB Server setup. + * + * @param institutionId The institution identifier + * @param configurationId The configuration identifier + * @param attributeResolver An attribute resolver function that gives an ConfigurationAttribute instance + * for the name of an attribute. + * @return Collection of all ConfigurationValue that must be applied to an newly created SEB exam configuration. */ Collection getAdditionalDefaultValues( Long institutionId, Long configurationId, diff --git a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigTemplateService.java b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigTemplateService.java index 8efe327e..485a543d 100644 --- a/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigTemplateService.java +++ b/src/main/java/ch/ethz/seb/sebserver/webservice/servicelayer/sebconfig/ExamConfigTemplateService.java @@ -14,29 +14,61 @@ import ch.ethz.seb.sebserver.gbl.model.sebconfig.TemplateAttribute; import ch.ethz.seb.sebserver.gbl.util.Result; import ch.ethz.seb.sebserver.webservice.servicelayer.dao.FilterMap; +/** The base interface and service for all SEB Exam Configuration Template related functionality. */ public interface ExamConfigTemplateService { + /** Use this to get filtered and sorted TemplateAttribute for a specified exam configuration template. + * + * @param institutionId The institution identifier of the exam configuration template + * @param templateId The exam configuration template identifier + * @param sort The sort column name + * @param filterMap The filter map containing all filter attributes + * @return Result revers to a sorted list of given TemplateAttribute or to an error if happened. */ Result> getTemplateAttributes( final Long institutionId, final Long templateId, final String sort, final FilterMap filterMap); + /** Use this to get a specified TemplateAttribute for a specified exam configuration template + * + * @param institutionId The institution identifier of the exam configuration template + * @param templateId The exam configuration template identifier + * @param attributeId The TemplateAttribute identifier */ Result getAttribute( final Long institutionId, final Long templateId, final Long attributeId); + /** Sets the default value for a specific TemplateAttribute on a specified exam configuration template + * + * @param institutionId The institution identifier of the exam configuration template + * @param templateId The exam configuration template identifier + * @param attributeId The TemplateAttribute identifier */ Result setDefaultValues( final Long institutionId, final Long templateId, final Long attributeId); + /** Removes the orientation from the view of a specified exam configuration template for a + * specific TemplateAttribute. This TemplateAttribute will then not be shown on the view anymore. + * + * @param institutionId The institution identifier of the exam configuration template + * @param templateId The exam configuration template identifier + * @param attributeId The TemplateAttribute identifier */ Result removeOrientation( final Long institutionId, final Long templateId, final Long attributeId); + /** Adds the orientation from the default view of a specified exam configuration template for a + * specific TemplateAttribute. This TemplateAttribute will then be shown on the specified view + * of the template. + * + * @param institutionId The institution identifier of the exam configuration template + * @param templateId The exam configuration template identifier + * @param attributeId The TemplateAttribute identifier + * @param viewId The view identifier to attach the TemplateAttribute to */ Result attachDefaultOrientation( final Long institutionId, final Long templateId, diff --git a/src/test/java/ch/ethz/seb/sebserver/gbl/model/ModelObjectJSONGenerator.java b/src/test/java/ch/ethz/seb/sebserver/gbl/model/ModelObjectJSONGenerator.java new file mode 100644 index 00000000..f24c12f7 --- /dev/null +++ b/src/test/java/ch/ethz/seb/sebserver/gbl/model/ModelObjectJSONGenerator.java @@ -0,0 +1,39 @@ +/* + * Copyright (c) 2020 ETH Zürich, Educational Development and Technology (LET) + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + */ + +package ch.ethz.seb.sebserver.gbl.model; + +import java.util.Arrays; +import java.util.HashSet; +import java.util.Locale; + +import org.joda.time.DateTime; +import org.joda.time.DateTimeZone; +import org.junit.Test; + +import com.fasterxml.jackson.databind.ObjectWriter; + +import ch.ethz.seb.sebserver.gbl.api.JSONMapper; +import ch.ethz.seb.sebserver.gbl.model.user.UserInfo; +import ch.ethz.seb.sebserver.gbl.model.user.UserRole; + +public class ModelObjectJSONGenerator { + + @Test + public void generateJSON() throws Exception { + final Object domainObject = new UserInfo("uuid", 1L, DateTime.now(), "name", "surname", "username", "email", + true, Locale.ENGLISH, DateTimeZone.UTC, + new HashSet<>(Arrays.asList(UserRole.EXAM_ADMIN.name(), UserRole.EXAM_SUPPORTER.name()))); + + final JSONMapper mapper = new JSONMapper(); + final ObjectWriter writerWithDefaultPrettyPrinter = mapper.writerWithDefaultPrettyPrinter(); + System.out.print(writerWithDefaultPrettyPrinter.writeValueAsString(domainObject)); + + } + +}