/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * @see javax.xml.bind.annotation.adapters.XmlAdapter#unmarshal(java.lang.Object)
 */
@Override
public NameAndNamespacePair unmarshal(NameAndNamespacePair v) throws Exception {
    if (v != null) {
        
        if (StringUtils.isBlank(v.getName())) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with a blank name");
        } else if (StringUtils.isBlank(v.getNamespaceCode())) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with a blank namespace code");
        } if (CoreServiceApiServiceLocator.getNamespaceService().getNamespace(v.getNamespaceCode()) == null) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with invalid or unknown namespace \"" +
                    v.getNamespaceCode() + "\"");
        }
        
        v.setName(new NormalizedStringAdapter().unmarshal(v.getName()));
        v.setNamespaceCode(v.getNamespaceCode());
    }
    return v;
}
 

/**
 * @see org.kuali.rice.core.util.jaxb.RiceXmlListAdditionListener#newItemAdded(java.lang.Object)
 */
public void newItemAdded(RoleXmlDTO item) {
    // Persist the role if it has not already been persisted yet.
    if (!item.isAlreadyPersisted()) {
        try {
            RoleXmlUtil.validateAndPersistNewRole(item);
        } catch (UnmarshalException e) {
            throw new RuntimeException(e);
        }
    }
    
    // If a "roleMembers" element was present, remove any existing roles that do not match the new ones.
    Set<String> existingRoleMemberIds = item.getExistingRoleMemberIds();
    if (existingRoleMemberIds != null) {
        RoleXmlUtil.removeRoleMembers(item.getRoleId(), existingRoleMemberIds);
    }
    item.setExistingRoleMemberIds(null);
}
 

/**
 * @see javax.xml.bind.annotation.adapters.XmlAdapter#unmarshal(java.lang.Object)
 */
@Override
public NameAndNamespacePair unmarshal(NameAndNamespacePair v) throws Exception {
    if (v != null) {
        
        if (StringUtils.isBlank(v.getName())) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with a blank name");
        } else if (StringUtils.isBlank(v.getNamespaceCode())) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with a blank namespace code");
        } if (CoreServiceApiServiceLocator.getNamespaceService().getNamespace(v.getNamespaceCode()) == null) {
            throw new UnmarshalException("Cannot import a name-and-namespace pair with invalid or unknown namespace \"" +
                    v.getNamespaceCode() + "\"");
        }
        
        v.setName(new NormalizedStringAdapter().unmarshal(v.getName()));
        v.setNamespaceCode(v.getNamespaceCode());
    }
    return v;
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Validates a permission to ensure that the required fields have been filled.
 * 
 * @throws UnmarshalException if newPermission contains invalid data.
 */
private static void validatePermission(PermissionXmlDTO newPermission) throws UnmarshalException {
    // Ensure that the permission name, namespace, template, and description have been filled in.
    if (StringUtils.isBlank(newPermission.getPermissionName()) || StringUtils.isBlank(newPermission.getNamespaceCode())) {
        throw new UnmarshalException("Cannot create a permission with a blank name or namespace");
    } else if (StringUtils.isBlank(newPermission.getPermissionTemplateId())) {
        throw new UnmarshalException("Cannot create a permission without specifying a permission template");
    } else if (StringUtils.isBlank(newPermission.getPermissionDescription())) {
        throw new UnmarshalException("Cannot create a permission with a blank description");
    }
    
    // If another permission with that name and namespace exists, use its ID on the new permission.
    PermissionContract permission = KimApiServiceLocator.getPermissionService().findPermByNamespaceCodeAndName(
            newPermission.getNamespaceCode(), newPermission.getPermissionName());
    if (permission != null) {
        newPermission.setPermissionId(permission.getId());
    }
}
 

@Test
public void testDTDInResults() throws Exception {
    URL resultsUrl = XMLConfigParserTest.class.getResource("/malicious_results_with_dtd.xml");
    assertNotNull(resultsUrl);
    File resultsFile = new File(resultsUrl.getFile());
    XMLResultHandler handler = new XMLResultHandler();
    try {
      handler.readFromResultFile(resultsFile);
      fail("Expected to see an exception parsing the results with a DTD");
    } catch (UnmarshalException e) {
      // If we don't parse the DTD, the variable 'name' won't be defined in the XML
      LOGGER.debug("Caught expected exception", e);
      Throwable cause = e.getLinkedException();
      assertTrue("Cause was a " + cause.getClass(), cause instanceof XMLStreamException);
    }
}
 

/**
 * Convert the given {@code JAXBException} to an appropriate exception from the
 * {@code org.springframework.oxm} hierarchy.
 * @param ex {@code JAXBException} that occurred
 * @return the corresponding {@code XmlMappingException}
 */
protected XmlMappingException convertJaxbException(JAXBException ex) {
	if (ex instanceof ValidationException) {
		return new ValidationFailureException("JAXB validation exception", ex);
	}
	else if (ex instanceof MarshalException) {
		return new MarshallingFailureException("JAXB marshalling exception", ex);
	}
	else if (ex instanceof UnmarshalException) {
		return new UnmarshallingFailureException("JAXB unmarshalling exception", ex);
	}
	else {
		// fallback
		return new UncategorizedMappingException("Unknown JAXB exception", ex);
	}
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * Reports an error to the user, and asks if s/he wants
 * to recover. If the canRecover flag is false, regardless
 * of the client instruction, an exception will be thrown.
 *
 * Only if the flag is true and the user wants to recover from an error,
 * the method returns normally.
 *
 * The thrown exception will be catched by the unmarshaller.
 */
public void handleEvent(ValidationEvent event, boolean canRecover ) throws SAXException {
    ValidationEventHandler eventHandler = parent.getEventHandler();

    boolean recover = eventHandler.handleEvent(event);

    // if the handler says "abort", we will not return the object
    // from the unmarshaller.getResult()
    if(!recover)    aborted = true;

    if( !canRecover || !recover )
        throw new SAXParseException2( event.getMessage(), locator,
            new UnmarshalException(
                event.getMessage(),
                event.getLinkedException() ) );
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * Reports an error to the user, and asks if s/he wants
 * to recover. If the canRecover flag is false, regardless
 * of the client instruction, an exception will be thrown.
 *
 * Only if the flag is true and the user wants to recover from an error,
 * the method returns normally.
 *
 * The thrown exception will be catched by the unmarshaller.
 */
public void handleEvent(ValidationEvent event, boolean canRecover ) throws SAXException {
    ValidationEventHandler eventHandler = parent.getEventHandler();

    boolean recover = eventHandler.handleEvent(event);

    // if the handler says "abort", we will not return the object
    // from the unmarshaller.getResult()
    if(!recover)    aborted = true;

    if( !canRecover || !recover )
        throw new SAXParseException2( event.getMessage(), locator,
            new UnmarshalException(
                event.getMessage(),
                event.getLinkedException() ) );
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * Reports an error to the user, and asks if s/he wants
 * to recover. If the canRecover flag is false, regardless
 * of the client instruction, an exception will be thrown.
 *
 * Only if the flag is true and the user wants to recover from an error,
 * the method returns normally.
 *
 * The thrown exception will be catched by the unmarshaller.
 */
public void handleEvent(ValidationEvent event, boolean canRecover ) throws SAXException {
    ValidationEventHandler eventHandler = parent.getEventHandler();

    boolean recover = eventHandler.handleEvent(event);

    // if the handler says "abort", we will not return the object
    // from the unmarshaller.getResult()
    if(!recover)    aborted = true;

    if( !canRecover || !recover )
        throw new SAXParseException2( event.getMessage(), locator,
            new UnmarshalException(
                event.getMessage(),
                event.getLinkedException() ) );
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Validates a new permission and then saves it.
 * 
 * @param newPermission
 * @throws IllegalArgumentException if newPermission is null.
 * @throws UnmarshalException if newPermission contains invalid data.
 */
static void validateAndPersistNewPermission(PermissionXmlDTO newPermission) throws UnmarshalException {
    if (newPermission == null) {
        throw new IllegalArgumentException("Cannot persist a null permission");
    }
    
    // Validate the new permission.
    validatePermission(newPermission);
    
    // Save the permission.
    Permission.Builder builder = Permission.Builder.create(newPermission.getNamespaceCode(), newPermission.getPermissionName());
    builder.setDescription(newPermission.getPermissionDescription());
    builder.setActive(newPermission.getActive().booleanValue());
    builder.setAttributes(newPermission.getPermissionDetails());
    
    KimApiServiceLocator.getPermissionService().createPermission(builder.build());
}
 

/**
 * Reports an error to the user, and asks if s/he wants
 * to recover. If the canRecover flag is false, regardless
 * of the client instruction, an exception will be thrown.
 *
 * Only if the flag is true and the user wants to recover from an error,
 * the method returns normally.
 *
 * The thrown exception will be catched by the unmarshaller.
 */
public void handleEvent(ValidationEvent event, boolean canRecover ) throws SAXException {
    ValidationEventHandler eventHandler = parent.getEventHandler();

    boolean recover = eventHandler.handleEvent(event);

    // if the handler says "abort", we will not return the object
    // from the unmarshaller.getResult()
    if(!recover)    aborted = true;

    if( !canRecover || !recover )
        throw new SAXParseException2( event.getMessage(), locator,
            new UnmarshalException(
                event.getMessage(),
                event.getLinkedException() ) );
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * Convert the given {@code JAXBException} to an appropriate exception from the
 * {@code org.springframework.oxm} hierarchy.
 * @param ex {@code JAXBException} that occured
 * @return the corresponding {@code XmlMappingException}
 */
protected XmlMappingException convertJaxbException(JAXBException ex) {
	if (ex instanceof ValidationException) {
		return new ValidationFailureException("JAXB validation exception", ex);
	}
	else if (ex instanceof MarshalException) {
		return new MarshallingFailureException("JAXB marshalling exception", ex);
	}
	else if (ex instanceof UnmarshalException) {
		return new UnmarshallingFailureException("JAXB unmarshalling exception", ex);
	}
	else {
		// fallback
		return new UncategorizedMappingException("Unknown JAXB exception", ex);
	}
}
 

/**
 * Validates a new role's name, namespace, KIM type, and description, and sets the role's ID if the name and namespace match an existing role.
 */
private static void validateAndPrepareRole(RoleXmlDTO newRole) throws UnmarshalException {
    // Ensure that the role name, role namespace, KIM type, and description have all been specified.
    if (StringUtils.isBlank(newRole.getRoleName()) || StringUtils.isBlank(newRole.getNamespaceCode())) {
        throw new UnmarshalException("Cannot create or override a role with a blank name or a blank namespace");
    } else if (StringUtils.isBlank(newRole.getKimTypeId())) {
        throw new UnmarshalException("Cannot create or override a role without specikfying a KIM type");
    } else if (StringUtils.isBlank(newRole.getRoleDescription())) {
        throw new UnmarshalException("Cannot create or override a role with a blank description");
    }
    
    // Attempt to find an existing matching role, and assign its ID to the validated role if it exists.
    String matchingId = KimApiServiceLocator.getRoleService().getRoleIdByNamespaceCodeAndName(
            newRole.getNamespaceCode(), newRole.getRoleName());
    if (StringUtils.isNotBlank(matchingId)) {
        newRole.setRoleId(matchingId);
    }
}
 

private static JAXBException handleStreamException(XMLStreamException e) {
    // StAXStreamConnector wraps SAXException to XMLStreamException.
    // XMLStreamException doesn't print its nested stack trace when it prints
    // its stack trace, so if we wrap XMLStreamException in JAXBException,
    // it becomes harder to find out the real problem.
    // So we unwrap them here. But we don't want to unwrap too eagerly, because
    // that could throw away some meaningful exception information.
    Throwable ne = e.getNestedException();
    if(ne instanceof JAXBException) {
        return (JAXBException)ne;
    }
    if(ne instanceof SAXException) {
        return new UnmarshalException(ne);
    }
    return new UnmarshalException(e);
}
 

/**
 * Creates an UnmarshalException from a SAXException.
 *
 * This is an utility method provided for the derived classes.
 *
 * <p>
 * When a provider-implemented ContentHandler wants to throw a
 * JAXBException, it needs to wrap the exception by a SAXException.
 * If the unmarshaller implementation blindly wrap SAXException
 * by JAXBException, such an exception will be a JAXBException
 * wrapped by a SAXException wrapped by another JAXBException.
 * This is silly.
 *
 * <p>
 * This method checks the nested exception of SAXException
 * and reduce those excessive wrapping.
 *
 * @return the resulting UnmarshalException
 */
protected UnmarshalException createUnmarshalException( SAXException e ) {
    // check the nested exception to see if it's an UnmarshalException
    Exception nested = e.getException();
    if(nested instanceof UnmarshalException)
        return (UnmarshalException)nested;

    if(nested instanceof RuntimeException)
        // typically this is an unexpected exception,
        // just throw it rather than wrap it, so that the full stack
        // trace can be displayed.
        throw (RuntimeException)nested;


    // otherwise simply wrap it
    if(nested!=null)
        return new UnmarshalException(nested);
    else
        return new UnmarshalException(e);
}
 

/**
 * @see javax.xml.bind.annotation.adapters.XmlAdapter#unmarshal(java.lang.Object)
 */
@Override
public Map<String, String> unmarshal(QualificationList v) throws Exception {
    if (v != null) {
        NormalizedStringAdapter normalizedStringAdapter = new NormalizedStringAdapter();
        Map<String, String> map = new HashMap<String, String>();
        for (MapStringStringAdapter.StringMapEntry stringMapEntry : v.getQualifications()) {
            String tempKey = normalizedStringAdapter.unmarshal(stringMapEntry.getKey());
            if (StringUtils.isBlank(tempKey)) {
                throw new UnmarshalException("Cannot create a qualification entry with a blank key");
            } else if (map.containsKey(tempKey)) {
                throw new UnmarshalException("Cannot create more than one qualification entry with a key of \"" + tempKey + "\"");
            }
            map.put(tempKey, normalizedStringAdapter.unmarshal(stringMapEntry.getValue()));
        }
    }
    return null;
}
 

/**
 * Performs the necessary validation on the new role, then saves it.
 * 
 * @param newRole The role to persist.
 * @return The ID of the persisted role.
 * @throws IllegalArgumentException if newRole is null.
 * @throws UnmarshalException if newRole contains invalid data.
 */
static String validateAndPersistNewRole(RoleXmlDTO newRole) throws UnmarshalException {
    if (newRole == null) {
        throw new IllegalArgumentException("Cannot persist a null role");
    }
    
    // Validate the role and (if applicable) retrieve the ID from an existing matching role.
    validateAndPrepareRole(newRole);

    Role.Builder builder = Role.Builder.create();
    builder.setActive(newRole.getActive());
    builder.setDescription(newRole.getRoleDescription());
    builder.setId(newRole.getRoleId());
    builder.setKimTypeId(newRole.getKimTypeId());
    builder.setName(newRole.getRoleName());
    builder.setNamespaceCode(newRole.getNamespaceCode());

    //save the role
    Role role = KimApiServiceLocator.getRoleService().createRole(builder.build());

    // Set a flag on the role to indicate that it has now been persisted so that the unmarshalling process will not save this role more than once.
    newRole.setAlreadyPersisted(true);
    
    return role.getId();
}
 

public void onException (@Nonnull final JAXBException ex)
{
  if (ex instanceof UnmarshalException)
  {
    // The JAXB specification does not mandate how the JAXB provider
    // must behave when attempting to unmarshal invalid XML data. In
    // those cases, the JAXB provider is allowed to terminate the
    // call to unmarshal with an UnmarshalException.
    final Throwable aLinked = ((UnmarshalException) ex).getLinkedException ();
    if (aLinked instanceof SAXParseException)
      LOGGER.error ("Failed to parse XML document: " + aLinked.getMessage ());
    else
      LOGGER.error ("Unmarshal exception reading document", ex);
  }
  else
    LOGGER.warn ("JAXB Exception reading document", ex);
}
 

/**
 * @see javax.xml.bind.annotation.adapters.XmlAdapter#unmarshal(java.lang.Object)
 */
@Override
public Map<String, String> unmarshal(QualificationList v) throws Exception {
    if (v != null) {
        NormalizedStringAdapter normalizedStringAdapter = new NormalizedStringAdapter();
        Map<String, String> map = new HashMap<String, String>();
        for (MapStringStringAdapter.StringMapEntry stringMapEntry : v.getQualifications()) {
            String tempKey = normalizedStringAdapter.unmarshal(stringMapEntry.getKey());
            if (StringUtils.isBlank(tempKey)) {
                throw new UnmarshalException("Cannot create a qualification entry with a blank key");
            } else if (map.containsKey(tempKey)) {
                throw new UnmarshalException("Cannot create more than one qualification entry with a key of \"" + tempKey + "\"");
            }
            map.put(tempKey, normalizedStringAdapter.unmarshal(stringMapEntry.getValue()));
        }
    }
    return null;
}