Use of names in DeploymentRepository SPI
brian.stansberry Mar 3, 2010 6:13 PMAs I'm working to clean up issues arising from the VFS3 switch, I'm finding the "name" concept in org.jboss.profileservice.spi.DeploymentRepository confusing and error prone. There are several different name concepts in the SPI and it's unclear how they should relate.
In my next post I'll get to conclusions, suggestions. People might want to skip the rest of this first post; in a lot of ways it's detailed notes for myself as I analyzed the SPI docs and the actual usage of it trying to clarify things for myself.
I see 3 different "name" concepts in the javadoc, deriving them from similar language in the javadoc describing params or return values:
- There's a "repostory name" notion, defined as "the unique name of the deployment in the repository". This language is used for
- the return value from addDeploymentContent(...)
- the "name" param passed to getDeploymentContent(...)
- the elements in the String[] returned by getRepositoryNames(....)
- A "vfs path" notion, defined as "the full vfs path of the deployment". This "vfs path" language is used for:
- the "name" param passed to addDeploymentContent(...)
- the "name" param passed to getDeploymentContent(...)
- the "name" param passed to (un)lockDeploymentContent(...
- the "name" param passed to the various xxxDeploymentContentFlags(...) methods
- A "deployment name" or "name of deployment" notion. This is used in various places, although it's unclear it's all the same notion:
- the elements in the Set<String> returned by getDeploymentNames()
- the "names" vararg passed to getRepositoryNames(...)
- the "name" param passed to addDeployment(...)
- the "name" param passed to getDeployment(...)
- the "name" param passed to removeDeployment(...)
- the value returned by ProfileDeployment.getName(), where ProfileDeployment is
- the "deployment" param passed to addDeployment(...)
- returned directly or indirectly from getDeployment, removeDeployment, getDeployments, getModifiedDeployments
That's looking at it from the SPI language point of view. Walking through some use cases it's clear that the above groupings based on common language are incorrect:
- User calls DeploymentManager.distribute("foo.war", someURL, true) and then DeploymentProgress.run();
- eventually calls server-side AbstractDeployHandler.handleStream()
- calls DeploymentRepository.addDeploymentContent("foo.war", ....) -- so the "vfs path" notion here is "foo.war". This call is really the inital entry point into DeploymentRepository usage, so for me this usage fixes the "vfs path" notion in the DeploymentRepository javadoc as meaning the same thing as the name param passed to DeploymentManager.distribute.
- the repository is dealing with multiple URIs so it has to decide where to place "foo.war". It decides on the URI ending with "farm/". So the "repository name" notion becomes "farm/foo.war". That's an implementation detail though; the repository could call it "bob" though if it wants
- the repository is dealing with multiple URIs so it has to decide where to place "foo.war". It decides on the URI ending with "farm/". So the "repository name" notion becomes "farm/foo.war". That's an implementation detail though; the repository could call it "bob" though if it wants
- calls DeploymentRepository.getDeploymentContent("farm/foo.war") to get a VirtualFile for the added content
- creates a "deploymentName" basically via a call to VirtualFile.toURI(). Why? Why not use the repositoryName? What if the repository called it "Bob" which has no relationship to VirtualFile.toURI()?
- this "deploymentName" becomes the "name" property of a new ProfileDeployment
- calls DeploymentRepository.addDeployment(deploymentName, ProfileDeployment)
- calls DeploymentRepository.lockDeployment(deploymentName). Seems 2.3 above is wrong; this param is deploymentName, not the initial vfs path
- returns the repositoryName back to the user
- calls DeploymentRepository.addDeploymentContent("foo.war", ....) -- so the "vfs path" notion here is "foo.war". This call is really the inital entry point into DeploymentRepository usage, so for me this usage fixes the "vfs path" notion in the DeploymentRepository javadoc as meaning the same thing as the name param passed to DeploymentManager.distribute.
- eventually calls server-side AbstractDeployHandler.handleStream()
- User calls DeploymentManager.start(repositoryName) i.e. start("farm/foo.war")
- eventually calls server-side AbstractDeployHander.start(DeploymentID);
- calls DeploymentRepository.getDeploymentNames() and validates it contains "farm/foo.war". Seems 3.1 above is wrong; that Set<String> returned by getDeploymentNames() is the repositoryName notion, not deploymentName
- calls DeploymentRepository.getDeployment(repositoryName). Seems 3.4 above is wrong; that param is a repositoryName not a deploymentName! It also means the DeploymentRepository.addDeployment(...) call above must use repositoryName, not deploymentName.
- calls DeploymentRepository.unlockDeployment(deploymentName) Seems 2.4 above is wrong; this param is deploymentName, not the initial vfs path
- calls DeploymentRepository.getDeploymentNames() and validates it contains "farm/foo.war". Seems 3.1 above is wrong; that Set<String> returned by getDeploymentNames() is the repositoryName notion, not deploymentName
- eventually calls server-side AbstractDeployHander.start(DeploymentID);
- User calls DeploymentManager.remove(repositoryName)
- eventually calls server-side AbstractDeployHander.start(DeploymentID);
- calls DeploymentRepository.getDeploymentNames() and validates it contains "farm/foo.war".
- calls DeploymentRepository.removeDeployment(repositoryName). Seems 3.5 above is wrong.
- eventually calls server-side AbstractDeployHander.start(DeploymentID);
- User calls DeploymentManager.distribute("foo.war", someURL, false) and DeploymentProgress.run();
- eventually calls server-side DeployHandler.distribute()
- creates a VirtualFile from someURL
- creates deploymentName from vf.toURI() -- so someURL essentially becomes deploymentName
- adds ProfileDeployment to transient profile
- returns deploymentName as repositoryName
- eventually calls server-side DeployHandler.distribute()
- Usage of DeploymentManager.getRepositoryNames()
- there are a couple places in the test suite where jar names are passed to DeploymentManager.distribute()
- which eventually passes the jar names to DeploymentRepository.addDeploymentContent()
- and then later the same jar names are passed to DeploymentManager.getRepositoryNames(...)
- which eventually passes them to DeploymentRepository.getRepositoryNames(...). Oops, seems 3.2 above is wrong; this param is the "vfs path" notion.
- there are a couple places in the test suite where jar names are passed to DeploymentManager.distribute()