* Analogous to how NamingException captures name resolution information, * LinkException captures "link"-name resolution information pinpointing * the problem encountered while resolving a link. All these fields may * be null. *
* A LinkException instance is not synchronized against concurrent * multithreaded access. Multiple threads trying to access and modify * a single LinkException instance should lock the object. * * @author Rosanna Lee * @author Scott Seligman * * @see Context#lookupLink * @see LinkRef * @since 1.3 */ /*
* The serialized form of a LinkException object consists of the * serialized fields of its NamingException superclass, the link resolved * name (a Name object), the link resolved object, link remaining name * (a Name object), and the link explanation String. */ public class LinkException extends NamingException { /** * Contains the part of the link that has been successfully resolved. * It is a composite name and can be null. * This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getLinkResolvedName * @see #setLinkResolvedName */ protected Name linkResolvedName; /** * Contains the object to which resolution of the part of the link was successful. * Can be null. This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getLinkResolvedObj * @see #setLinkResolvedObj */ protected Object linkResolvedObj; /** * Contains the remaining link name that has not been resolved yet. * It is a composite name and can be null. * This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getLinkRemainingName * @see #setLinkRemainingName */ protected Name linkRemainingName; /** * Contains the exception of why resolution of the link failed. * Can be null. This field is initialized by the constructors. * You should access and manipulate this field * through its get and set methods. * @serial * @see #getLinkExplanation * @see #setLinkExplanation */ protected String linkExplanation; /** * Constructs a new instance of LinkException with an explanation * All the other fields are initialized to null. * @param explanation A possibly null string containing additional * detail about this exception. * @see java.lang.Throwable#getMessage */ public LinkException(String explanation) { super(explanation); linkResolvedName = null; linkResolvedObj = null; linkRemainingName = null; linkExplanation = null; } /** * Constructs a new instance of LinkException. * All the non-link-related and link-related fields are initialized to null. */ public LinkException() { super(); linkResolvedName = null; linkResolvedObj = null; linkRemainingName = null; linkExplanation = null; } /** * Retrieves the leading portion of the link name that was resolved * successfully. * * @return The part of the link name that was resolved successfully. * It is a composite name. It can be null, which means * the link resolved name field has not been set. * @see #getLinkResolvedObj * @see #setLinkResolvedName */ public Name getLinkResolvedName() { return this.linkResolvedName; } /** * Retrieves the remaining unresolved portion of the link name. * @return The part of the link name that has not been resolved. * It is a composite name. It can be null, which means * the link remaining name field has not been set. * @see #setLinkRemainingName */ public Name getLinkRemainingName() { return this.linkRemainingName; } /** * Retrieves the object to which resolution was successful. * This is the object to which the resolved link name is bound. * * @return The possibly null object that was resolved so far. * If null, it means the link resolved object field has not been set. * @see #getLinkResolvedName * @see #setLinkResolvedObj */ public Object getLinkResolvedObj() { return this.linkResolvedObj; } /** * Retrieves the explanation associated with the problem encounter * when resolving a link. * * @return The possibly null detail string explaining more about the problem * with resolving a link. * If null, it means there is no * link detail message for this exception. * @see #setLinkExplanation */ public String getLinkExplanation() { return this.linkExplanation; } /** * Sets the explanation associated with the problem encounter * when resolving a link. * * @param msg The possibly null detail string explaining more about the problem * with resolving a link. If null, it means no detail will be recorded. * @see #getLinkExplanation */ public void setLinkExplanation(String msg) { this.linkExplanation = msg; } /** * Sets the resolved link name field of this exception. *
* name is a composite name. If the intent is to set * this field using a compound name or string, you must * "stringify" the compound name, and create a composite * name with a single component using the string. You can then * invoke this method using the resulting composite name. *
* A copy of name is made and stored.
* Subsequent changes to name does not
* affect the copy in this NamingException and vice versa.
*
*
* @param name The name to set resolved link name to. This can be null.
* If null, it sets the link resolved name field to null.
* @see #getLinkResolvedName
*/
public void setLinkResolvedName(Name name) {
if (name != null) {
this.linkResolvedName = (Name)(name.clone());
} else {
this.linkResolvedName = null;
}
}
/**
* Sets the remaining link name field of this exception.
*
* name is a composite name. If the intent is to set * this field using a compound name or string, you must * "stringify" the compound name, and create a composite * name with a single component using the string. You can then * invoke this method using the resulting composite name. *
* A copy of name is made and stored.
* Subsequent changes to name does not
* affect the copy in this NamingException and vice versa.
*
* @param name The name to set remaining link name to. This can be null.
* If null, it sets the remaining name field to null.
* @see #getLinkRemainingName
*/
public void setLinkRemainingName(Name name) {
if (name != null)
this.linkRemainingName = (Name)(name.clone());
else
this.linkRemainingName = null;
}
/**
* Sets the link resolved object field of this exception.
* This indicates the last successfully resolved object of link name.
* @param obj The object to set link resolved object to. This can be null.
* If null, the link resolved object field is set to null.
* @see #getLinkResolvedObj
*/
public void setLinkResolvedObj(Object obj) {
this.linkResolvedObj = obj;
}
/**
* Generates the string representation of this exception.
* This string consists of the NamingException information plus
* the link's remaining name.
* This string is used for debugging and not meant to be interpreted
* programmatically.
* @return The non-null string representation of this link exception.
*/
public String toString() {
return super.toString() + "; Link Remaining Name: '" +
this.linkRemainingName + "'";
}
/**
* Generates the string representation of this exception.
* This string consists of the NamingException information plus
* the additional information of resolving the link.
* If 'detail' is true, the string also contains information on
* the link resolved object. If false, this method is the same
* as the form of toString() that accepts no parameters.
* This string is used for debugging and not meant to be interpreted
* programmatically.
*
* @param detail If true, add information about the link resolved
* object.
* @return The non-null string representation of this link exception.
*/
public String toString(boolean detail) {
if (!detail || this.linkResolvedObj == null)
return this.toString();
return this.toString() + "; Link Resolved Object: " +
this.linkResolvedObj;
}
/**
* Use serialVersionUID from JNDI 1.1.1 for interoperability
*/
private static final long serialVersionUID = -7967662604076777712L;
};