1 package org.codehaus.mojo.jaxb2.schemageneration.postprocessing.javadoc.location;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import org.codehaus.mojo.jaxb2.shared.Validate;
23
24 import javax.xml.bind.annotation.XmlAttribute;
25 import javax.xml.bind.annotation.XmlElement;
26 import javax.xml.bind.annotation.XmlType;
27
28 /**
29 * Comparable path structure to locate a particular class within compilation unit.
30 *
31 * @author <a href="mailto:lj@jguru.se">Lennart Jörelid</a>, jGuru Europe AB
32 * @since 2.0
33 */
34 public class ClassLocation extends PackageLocation {
35
36 // Internal state
37 private String className;
38 private String classXmlName;
39
40 /**
41 * Creates a new ClassLocation with the supplied package and class names.
42 *
43 * @param packageName The name of the package for a class potentially holding JavaDoc. Cannot be {@code null}.
44 * @param classXmlName The name given as the {@link XmlType#name()} value of an annotation placed on the Class,
45 * or {@code null} if none is provided.
46 * @param className The (simple) name of a class. Cannot be null or empty.
47 */
48 public ClassLocation(final String packageName, final String className, final String classXmlName) {
49
50 super(packageName);
51
52 // Check sanity
53 Validate.notEmpty(className, "className");
54
55 // Assign internal state
56 this.className = className;
57 this.classXmlName = classXmlName;
58 }
59
60 /**
61 * Retrieves the simple class name for the class potentially holding JavaDoc. Never {@code null} or empty.
62 *
63 * @return The simple class name for the class potentially holding JavaDoc. Never {@code null} or empty.
64 */
65 public String getClassName() {
66 return classXmlName == null ? className : classXmlName;
67 }
68
69 /**
70 * Always appends the <strong>effective className</strong> to the path from the superclass {@link PackageLocation}.
71 * If the {@link #getAnnotationRenamedTo()} method returns a non-null value, that value is the effective className.
72 * Otherwise, the {@link #getClassName()} method is used as the effective className.
73 *
74 * This is to handle renames such as provided in a {@link javax.xml.bind.annotation.XmlType} annotation's
75 * {@link XmlType#name()} attribute value.
76 *
77 * @return the path of the PackageLocation superclass, appended with the effective className.
78 * @see XmlType
79 * @see XmlAttribute#name()
80 * @see XmlElement#name()
81 */
82 @Override
83 public String getPath() {
84 return super.toString() + "." + getClassName();
85 }
86
87 /**
88 * {@inheritDoc}
89 */
90 @Override
91 public String getAnnotationRenamedTo() {
92 return classXmlName;
93 }
94
95 /**
96 * {@inheritDoc}
97 */
98 @Override
99 public int hashCode() {
100 return this.toString().hashCode();
101 }
102
103 /**
104 * {@inheritDoc}
105 */
106 @Override
107 public String toString() {
108
109 final String xmlOverriddenFrom = classXmlName != null && !className.equals(classXmlName)
110 ? " (from: " + className + ")"
111 : "";
112
113 return super.toString() + "." + getClassName() + xmlOverriddenFrom;
114 }
115 }