4:54 p.m.
(This is a long email - it is for people involved in deploying applications via the
Hawkular WildFly Agent. If you are writing UI code to deploy/undeploy, I suggest you read
it. Send questions/comments - because I'm not even sure if I understand everything
100%)
I just realized why there is confusion regarding how to tell the agent to
deploy/undeploy/remove applications.
There are different operations on different resources that do apparently the same thing.
But I think this is mainly due to the fact the agent is trying to support both standalone
and domain modes and to make it easier on the clients.
On the "WildFly Server" resource (which is the standalone server), these
operations are defined by the agent:
<operation-dmr name="Deploy" internal-name="deploy"/>
<operation-dmr name="Undeploy" internal-name="undeploy"/>
On the "Host Controller" resource (which is only in domain mode), there are
these same two operations defined.
So, you can deploy an application through the "WildFly Server" (standalone mode)
and "Host Controller" (domain mode) - you need to pass in content when you do
this, hence why DeployApplicationRequest JSON has to be used.
But notice you can also undeploy an application through those top level resources as well.
You do this via UndeployApplicationRequest JSON.
Why don't we use ExecuteOperationRequest JSON here but instead require these two
special JSON commands? Because there is no "deploy" or "undeploy" DMR
operations on those wildfly resources (i.e. the top level server or host controller).
However, there are several deploy/undeploy related DMR operations - like
full-replace-deployment, upload-deployment-bytes, replace-deployment, etc. But rather than
force the UI clients to have to know about all of these, the agent provides just the
simple "Deploy" and "Undeploy" which do what you'd expect them to
do. We make it easy by providing some flags in the DeployApplicationRequest JSON to let
you say if you want it enabled or not and the agent will always force the deployment (that
means, if there was already a deployment, the new deployment replaces the old). So the
client doesn't have to fool around with the different combinations ("does this
deployment already exist? No? Then just send in the content. Do you want it enabled?
Deploy it, too. Yes, deployment already exists? Then send a undeploy command first, then
send a remove command, then send a deploy command - or whatever WildFly wants you to do,
I'm not even sure").
The agent is using the new wildfly maven core API to do the deploy and undeploy - so its
very easy to wrap that stuff around our Deploy/Undeploy stuff - we let that library deal
with all the details on how to do this. This, again, is why we don't use
ExecuteOperationRequest - because if we did, the CLIENT would have to do all the stuff
this wildfly maven core API does to get content to be deployed.
OK, but it gets more confusing because now if you look at the deployment resources, there
are ANOTHER set of operations dealing with deploy/undeploy and these DO USE
ExecuteOperationRequest JSON to invoke them (because these really do just pass through to
the WildFly management controller and execute as is).
For example, on any deployment inside a standalone server you will see these:
/deployment=hawkular-rest-api.war/:read-operation-names
{
"deploy",
"redeploy",
"remove",
"undeploy",
}
Very confusing to have "deploy" on an deployment!! It is already deployed! I
don't fully understand this, but I think this is to deploy an application whose
content is uploaded but is NOT enabled. You'll see that deployment resource exists in
the server but its not "enabled" because it isn't deployed. You
"enable" it by deploying it.
And you'll see here you can redeploy the app, remove it (that removes the content
entirely I believe - I think the entire deployment resource goes away when you do this),
and undeploy (which to me means "disable").
This is why you will see a separate set of deployment related operations defined in the
agent's "Deployment" resource type:
<operation-dmr name="Redeploy" internal-name="redeploy"/>
<operation-dmr name="Remove" internal-name="remove"/>
<operation-dmr name="Undeploy" internal-name="undeploy"/>
Very confusing indeed, but these are meant to be executed via the ExecuteOperationRequest
JSON and they map one-to-one to the WildFly's operations that I showed above. Note
there is no "Deploy" that we map - there is no reason for that other than it
probably didn't make sense to us to add it. And I'm not even sure if the client
should be executing these operations IF IN DOMAIN MODE! You should be going through the
host controller to deploy and undeploy applications when in domain mode.
Clear as mud?
So the next question is - which ones should we be using? Send ExecuteOperationRequest JSON
to the "Deployment" resource itself? Or (Un)DeployApplicationRequest JSON to the
top level Server/HostController?
To my mind, we should be using the (Un)DeployApplicationRequest JSON on the top level
servers. I am almost thinking we should remove the <operation-dmr> definitions for
the Redeploy/Remove/Undeploy on the Deployment resources themselves - you really should
only be using those when in standalone mode (so your client now has to know to only call
them if the server is in standalone mode) and it just adds a second way to do something
which makes it confusing to know which to use.
I think there should be a design meeting with all the involved parties (developers, UI
design, requirement authors) so we can figure out what we really need. I know this is in
the PRD but quite honestly that's like reading the fine print of a legal document and
my eyes glaze over before I finish the first paragraph.