CPS-2240 Restructure NCMP DataJobs feature in NCMP Service

Owned by Toine Siebelink
Last updated: Jul 09, 2024
2 min read

References

CPS-2240: Restructure(package) DataJobs feature in NCMP ServiceClosed

Issues & Decisions

Issue

Notes 

Decision

Issue

Notes 

Decision

1

use api and impl folders

 

May 23, 2024 Team agreed on separate top level ap and impl folders. Common impl folders can be at top level ie. not under impl.
any class in api should not depend (i.e. nor import) anything from impl or common folders!!!  

2

use feature based packages

 

May 23, 2024 Team agreed to use the current 4 services (or 5 depending on inventory)  as feature folders directly under impl and some also under api

The following feature structure emerged during the actual refactoring

  • cmsubscriptions (TBC)

  •  data

    • async

  • datajobs

  • inventory

    • sync

      • lcm

    • trustlevel

3

when to use common packages

 

May 23, 2024 when in doubt use common package e.g. exceptions might be re-used for other features in the future
However just because it is used by another feature doesn't mean it is common. e.g. a Class to check th state of a cm-handle could be used anywhere but still very much belong to the 'inventory' feature

4

scope

 

May 23, 2024 currently only ncmp-service in scope. 

5

plan

 

May 23, 2024 team agreed to do trial with 'datajobs' first. Code need to be reviewed by both teams. Once this is completed we will address 'legacy' services

Proposed Generic Structure

Package

Scope

Notes

Package

Scope

Notes

1

api

all classes that are required for northbound interfaces

classes that are directly used by the REST interface (or controllers)

2

api\feature

all API classes that are specific to a given feature

 

3

api\feature\models

all data-holder type classes for the API specific to the feature

do NOT add data objects that are only used in the impl!

4

api\feature\exceptions

all exception classes that are specific to a given feature

do think 'ahead': is the exception rally going to be unique for this feature! 
If in doubt it probably should go into api\exception. Because moving it later would be a backward incompatible change!

5

api\models

all data-holder type classes for the API that can be shared between features

 

6

api\feature\exceptions

all exception classes that can be shared between features and at least oen feature exposes on the API

 

7

impl

all classes that are NOT exposed on the northbound interface and are unique to just one feature

since these classes are NOT exposed on the API it is OK to move them to the common utils\ package only when needed (i.e. later) since this would not be backward incompatible

8

impl\feature

all implementation classes that are specific to a given feature

a feature could be NOT direct used by a API feature but maybe api features can depend on a common implementation feature such as 'trustlevel' or 'sync/data' and 'sync/module'

9

exceptions

all exception classes that can be shared between given features and are NOT exposed on any API

 

10

utils

all  implementation classes that can be shared between features but don't belong to a specific feature

even if classes are used by several API feature that doesn't mean thry have to go here. They can stull be part of a common (impl. only) feature e.g. TrustLevel

11

models

all data-holder type classes used in impl only that can be shared between features

 

 

Generic folder (package structure)
api\feature1\SomeService.class api\feature1\models\SpecificModelClass api\feature1\exceptions\SpecificException.class api\feature2\SomeService.class api\feature2\models\SpecificModelclass api\feature2\exceptions\SpecificException.class api\models\CommonModel.class api\exeptions\CommonException.class impl\feature1\SomeServiceImpl.class impl\feature1\helperPackage\SpecificHelper.class impl\feature2\SomeServiceImpl.class exceptions\someInternalException.class utils\CommonHelper.class

Proposed DataJobs Structure

Proposed structure (not complete but indicative):

datajobs
api\datajobs\DataJobsService.class api\datajobs\models\DataJobMetadata.class api\datajobs\models\DataJobReadRequest.class api\datajobs\models\DataJobWriteRequest.class impl\datajobs\DataJobsServiceImpl.class exceptions\NoAlternateIdParentFoundException.class utils\AlternateIdMatcher.class

Proposed User Stories