Nsf Base

NsfBase is responsible for storing and organizing your local files:

  • sourceBases – cloned projects and models
  • expandBases – expansion locations
  • deployBases – local deployments

You can have as many NsfBases as you want, but at least one is expected. Furthermore you can have specialized bases (e.g. one only for source code, another only for deployment, etc).

Each nsfBase is scanned from Prime Radiant (using Synchronize or Synchronize All buttons) and data automatically imported.

Minimal, but complete NsfBase:

  • <nsfRoot> – can be anywhere (e.g. C:\NSF)
    • /infrastructure
      • /tomee-plume-8.0.0
        • tomee-marker.xml – deployBaseType marker file for NsfBase scanner
          <deployBaseType name="TomEE Plume 8.0.0">
            <technology name="TOMEE"/>
          </deployBaseType>
          
        • /BASE7 – deployBase directory (matched using /BASE.*/ in scanner)
    • /primespace
      • /expansions
        • /expand-here.xml – expandBase marker file for scanner
          <expandBase name="Expansions"/>
          
        • /bookingApp_experimental/bookingApp expanded application
          • using pattern <applicationInstance.name>/<application.name>
    • /workspace
      • /demobookingapp – root of a project and a root of a sourceBase
        • /**/bookingApp-1.0.xml
          <application name="bookingApp">
            <!-- ... -->
              <modelRepository name="bookingAppBase"/>
              <customRepository name="bookingAppBase"/>
            <!-- ... -->
          </application>
          
        • /**/demoBooking.xml
          <component name="demoBooking">
            <!-- ... -->
              <modelRepository name="bookingAppBase"/>
              <customRepository name="bookingAppBase"/>
            <!-- ... -->
          </component>
          
  • The naming of infrastructure/primespace/workspace directories can be anything
  • Content can be mixed (e.g. expandBase and deployBase inside sourceBase), as long as the marker files exist and are at the same depth from the <nsfRoot>
  • Applications/Components can be up to ~6 levels deep
    • e.g. <nsfRoot>/workspace/demobookingapp/src/main/resources/applications/bookingApp/model/bookingApp-1.0.xml
  • The scanner will create a new sourceBase for every unique <modelRepository> and <customRepository> found in the sourceBase
    • we recommend using the same name everywhere within a single project



WARNING: Work In Progress

  • <nsfRoot> – can be anywhere (e.g. C:\NSF)
    • /infrastructure<subspace.name> ::= "infrastructure"
      • /tomee-plume-8.0.0<deployBaseType.subDirectory> ::= "tomee-plume-8.0.0"
        • /BASE7
          • <deployBase.nsfBase> ::= <nsfRoot>
          • <deployBase.subspace> ::= <subspace:infrastructure>
          • <deployBase.baseRoot> ::= "BASE7"
          • <deployBase.type> ::= <deployBaseType:tomee-plume-8.0.0>
    • /primespace<subspace.name> ::= "primespace"
      • /expansionsPR
        • <expandBase.nsfBase> ::= <nsfRoot>
        • <expandBase.subspace> ::= <subspace:primespace>
        • <expandBase.baseRoot> ::= "expansionPR"
        • /primeTest-id33637 not represented by an NS element
    • /workspace<subspace.name> ::= "workspace"
      • /primeTestApp
        • <sourceBase.nsfBase> ::= <nsfRoot>
        • <sourceBase.subspace> ::= <subspace:workspace>
        • <sourceBase.baseRoot> ::= "primeTestApp"

Servers/DeployBaseType Detection

For servers, (2) & (3) it further fuzzy-matches them to JOnAS or TomEE technologies, for (1) it just reads the file. The fuzzy matching should be removed, because it’s only for two servers, and even for tomee requires prior renaming (normally it’s apache-tomee-*).

To resolve: Force all servers to contain <deployBaseType> file?

To autodetect all severs in an <nsfBase>, we basically need to look for all files in depth 3 and check whether they happen to be <deployBaseType> xml files:

<nsfRoot>/<any subspace name>/<any server name>/<file>.xml

However I would like to run this check/sync on every PR startup, and when requested by the user from UI

To resolve: Is it expensive to check all XML files at this depth? Because this would be also checking all projects cloned in workspace (although only files in their root directory). I don’t like scanning too much, but maybe looking at ~100 of files every startup is actually free.

Workspaces/SourceBase Detection

As for source bases, checking all subdirectories of <nsfRoot> is probably cheaper than the server detection, because we can halt at directory name checking, and don’t need to read & parse XML files.

<nsfRoot>/<subspace:workspace>/<applications|components>/model/<file>.xml

On the other hand this would not detect use-cases where e.g. the applications and/or components are in a subdirectory, such as (iirc streaming component of digipolis), and the source of baseComponents, which need:

<sourceBase.name> ::= "BaseComponents"
<sourceBase.subspace> ::= <subspace>`
<sourceBase.baseRoot> ::= "base-components/base-components-model/src/main/resources"

Sure, people can create it by hand, but I want to completely purge that concept from people’s mind, and just do it automatically as much as possible.

Perhaps for this we can require that each project (that wants auto-syncing) has in their root a modelResource file?

<!-- for Prime Radiant -->
<!-- in /base-components/models.xml -->
<modelResource>
  <path>base-components-model/src/main/resources/components</path>
</modelResource>

<!-- For expanders-maven-plugin -->
<!-- in /base-components/base-components-model/src/main/resources/components/models.xml -->
<modelResource>
  <path>components</path>
</modelResource>

Alternatively we can look at the default <somewhere>/conf/expansionSettings.xml file, and pick the model directories that are placed in the the same <somewhere> (i.e. it would ignore paths that point outside of the <somewhere> directory).

SourceBase is referred to from your application and component xmls via the modelRepository and customRepository tags. We look for all such files in the NsfBase and create source bases for them.

For existing projects: all you need to do is clone your project to any subdirectory of the NsfBase (e.g. to C:\NSF\workspace or O:\wherever\mySpecialNsfBase\myProjects).

SourceBases – Scanning

The search pattern is

<nsfRoot>/<subspace>/<sourceBaseRoot>/<applications|components>/<name>/model/<file>.xml

Where:

  • <nsfRoot> == <nsfBase.baseRoot>
    • examples
      • C:\NSF
      • O:\prime-radiant\dist
  • <subspace> == <sourceBase.subspace.name>
    • single directory name
    • examples
      • workspace
      • repositories
  • <sourceBaseRoot> == <sourceBase.baseRoot>
    • relative path up to 5 directories deep
      • from subspace to a directory containing applications or components directories
    • examples:
      • demobookingapp
      • base-components/base-components-model/target/classes

WARNING: SourceBases use their name as an unique identifier. Have multiple different source base directories using the same name will result in errors when trying to import/export your models.

Expansion/ExpandBase Detection

We have no detection for this, but we can probably detect it by looking adding the necessary file directly to the target directory.

This probably should sync in both directions; e.g. when something is configured in PR, but the directories don’t exist on disk (or the <expandBase>.xml file is missing, it will create the directories / add the files).