Ensures that the given application is deployed on server.

    jboss_config:
        Dict with connection properties (see state description)
    salt_source:
        How to find the artifact to be deployed.
            target_file:
                Where to look in the minion's file system for the artifact to be deployed (e.g. '/tmp/application-web-0.39.war').  When source is specified,  also specifies where to save the retrieved file.
            source:
                (optional) File on salt master (e.g. salt://application-web-0.39.war).  If absent, no files will be retrieved and the artifact in target_file will be used for the deployment.
            undeploy:
                (optional) Regular expression to match against existing deployments.  When present, if there is a deployment that matches the regular expression, it will be undeployed before the new artifact is deployed.
            undeploy_force:
                (optional) If True, the artifact will be undeployed although it has not changed.

    Examples:

    Deployment of a file from minion's local file system:

    .. code-block:: yaml

        application_deployed:
          jboss7.deployed:
            - salt_source:
                target_file: '/tmp/webapp.war'
            - jboss_config: {{ pillar['jboss'] }}

    It is assumed that /tmp/webapp.war was made available by some
    other means.  No applications will be undeployed; if an existing
    deployment that shares that name exists, then it will be replaced
    with the updated version.

    Deployment of a file from the Salt master's file system:

    .. code-block:: yaml

        application_deployed:
          jboss7.deployed:
           - salt_source:
                source: salt://application-web-0.39.war
                target_file: '/tmp/application-web-0.39.war'
                undeploy: 'application-web-.*'
           - jboss_config: {{ pillar['jboss'] }}

    Here, application-web-0.39.war file is downloaded from Salt file system to /tmp/application-web-0.39.war file on minion.
    Existing deployments are checked if any of them matches 'application-web-.*' regular expression, and if so then it
    is undeployed before deploying the application. This is useful to automate deployment of new application versions.

    If the source parameter of salt_source is specified, it can use
    any protocol that the file states use.  This includes not only
    downloading from the master but also HTTP, HTTPS, FTP,
    Amazon S3, and OpenStack Swift.

def deployed(name, jboss_config, salt_source=None):
    '''Ensures that the given application is deployed on server.

    jboss_config:
        Dict with connection properties (see state description)
    salt_source:
        How to find the artifact to be deployed.
            target_file:
                Where to look in the minion's file system for the artifact to be deployed (e.g. '/tmp/application-web-0.39.war').  When source is specified,  also specifies where to save the retrieved file.
            source:
                (optional) File on salt master (e.g. salt://application-web-0.39.war).  If absent, no files will be retrieved and the artifact in target_file will be used for the deployment.
            undeploy:
                (optional) Regular expression to match against existing deployments.  When present, if there is a deployment that matches the regular expression, it will be undeployed before the new artifact is deployed.
            undeploy_force:
                (optional) If True, the artifact will be undeployed although it has not changed.

    Examples:

    Deployment of a file from minion's local file system:

    .. code-block:: yaml

        application_deployed:
          jboss7.deployed:
            - salt_source:
                target_file: '/tmp/webapp.war'
            - jboss_config: {{ pillar['jboss'] }}

    It is assumed that /tmp/webapp.war was made available by some
    other means.  No applications will be undeployed; if an existing
    deployment that shares that name exists, then it will be replaced
    with the updated version.

    Deployment of a file from the Salt master's file system:

    .. code-block:: yaml

        application_deployed:
          jboss7.deployed:
           - salt_source:
                source: salt://application-web-0.39.war
                target_file: '/tmp/application-web-0.39.war'
                undeploy: 'application-web-.*'
           - jboss_config: {{ pillar['jboss'] }}

    Here, application-web-0.39.war file is downloaded from Salt file system to /tmp/application-web-0.39.war file on minion.
    Existing deployments are checked if any of them matches 'application-web-.*' regular expression, and if so then it
    is undeployed before deploying the application. This is useful to automate deployment of new application versions.

    If the source parameter of salt_source is specified, it can use
    any protocol that the file states use.  This includes not only
    downloading from the master but also HTTP, HTTPS, FTP,
    Amazon S3, and OpenStack Swift.

    '''
    log.debug(" ======================== STATE: jboss7.deployed (name: %s) ", name)
    ret = {'name': name,
           'result': True,
           'changes': {},
           'comment': ''}

    comment = ''

    validate_success, validate_comment = __validate_arguments(jboss_config, salt_source)
    if not validate_success:
        return _error(ret, validate_comment)

    resolved_source, get_artifact_comment, changed = __get_artifact(salt_source)
    log.debug('resolved_source=%s', resolved_source)
    log.debug('get_artifact_comment=%s', get_artifact_comment)

    comment = __append_comment(new_comment=get_artifact_comment, current_comment=comment)
    if resolved_source is None:
        return _error(ret, get_artifact_comment)

    find_success, deployment, find_comment = __find_deployment(jboss_config, salt_source)
    if not find_success:
        return _error(ret, find_comment)

    require_deployment = True

    log.debug('deployment=%s', deployment)
    if deployment is not None:
        if 'undeploy_force' in salt_source:
            if salt_source['undeploy_force']:
                ret['changes']['undeployed'] = __undeploy(jboss_config, deployment)
            else:
                if changed:
                    ret['changes']['undeployed'] = __undeploy(jboss_config, deployment)
                else:
                    require_deployment = False
                    comment = __append_comment(new_comment='The artifact {} was already deployed'.format(deployment), current_comment=comment)
        else:
            ret['changes']['undeployed'] = __undeploy(jboss_config, deployment)

    if require_deployment:
        deploy_result = __salt__['jboss7.deploy'](jboss_config=jboss_config, source_file=resolved_source)
        log.debug('deploy_result=%s', str(deploy_result))
        if deploy_result['success']:
            comment = __append_comment(new_comment='Deployment completed.', current_comment=comment)
            ret['changes']['deployed'] = resolved_source
        else:
            comment = __append_comment(new_comment='''Deployment failed\nreturn code={retcode}\nstdout='{stdout}'\nstderr='{stderr}'''.format(**deploy_result), current_comment=comment)
            _error(ret, comment)

    ret['comment'] = comment

    return ret