001/* 002 * ============================================================================ 003 * Copyright © 2015 Square, Inc. 004 * Copyright for the modifications © 2018-2024 by Thomas Thrien. 005 * ============================================================================ 006 * 007 * Licensed under the Apache License, Version 2.0 (the "License"); 008 * you may not use this file except in compliance with the License. 009 * You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, software 014 * distributed under the License is distributed on an "AS IS" BASIS, 015 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 016 * See the License for the specific language governing permissions and 017 * limitations under the License. 018 */ 019 020package org.tquadrat.foundation.javacomposer; 021 022import static org.apiguardian.api.API.Status.STABLE; 023 024import javax.lang.model.element.TypeElement; 025import java.util.List; 026import java.util.Map; 027import java.util.Optional; 028 029import org.apiguardian.api.API; 030import org.tquadrat.foundation.annotation.ClassVersion; 031import org.tquadrat.foundation.javacomposer.internal.ClassNameImpl; 032 033/** 034 * The specification for a fully-qualified class name for top-level and 035 * member classes. 036 * 037 * @author Square,Inc. 038 * @modified Thomas Thrien - thomas.thrien@tquadrat.org 039 * @version $Id: ClassName.java 1085 2024-01-05 16:23:28Z tquadrat $ 040 * @since 0.0.5 041 * 042 * @UMLGraph.link 043 */ 044@ClassVersion( sourceVersion = "$Id: ClassName.java 1085 2024-01-05 16:23:28Z tquadrat $" ) 045@API( status = STABLE, since = "0.0.5" ) 046public sealed interface ClassName extends TypeName, Comparable<ClassName> 047 permits ClassNameImpl 048{ 049 /*---------*\ 050 ====** Methods **========================================================== 051 \*---------*/ 052 /** 053 * Creates a new instance for an implementation of {@code ClassName} as a 054 * copy of this one, but with the given annotations added. 055 * 056 * @param annotations The annotations. 057 * @return The new instance. 058 */ 059 @Override 060 public ClassName annotated( final List<AnnotationSpec> annotations ); 061 062 /** 063 * {@inheritDoc} 064 */ 065 @Override 066 public int compareTo( final ClassName o ); 067 068 /** 069 * Returns the canonical form of the class name. 070 * 071 * @return The canonical name. 072 */ 073 public String canonicalName(); 074 075 /** 076 * {@inheritDoc} 077 */ 078 @SuppressWarnings( "AbstractMethodOverridesAbstractMethod" ) 079 @Override 080 public boolean equals( final Object o ); 081 082 /** 083 * Creates a new instance for an implementation of {@code ClassName} from 084 * an instance of 085 * {@link Class}. 086 * 087 * @param sourceClass The instance of {@code java.lang.Class}. 088 * @return The respective instance of {@code ClassName}. 089 */ 090 @SuppressWarnings( "ClassReferencesSubclass" ) 091 @API( status = STABLE, since = "0.2.0" ) 092 public static ClassName from( final Class<?> sourceClass ) 093 { 094 final var retValue = ClassNameImpl.from( sourceClass ); 095 096 // ---* Done *---------------------------------------------------------- 097 return retValue; 098 } // from() 099 100 /** 101 * Returns the class name for the given 102 * {@link TypeElement} 103 * instance. 104 * 105 * @param element The type element instance. 106 * @return The new class name instance. 107 */ 108 @SuppressWarnings( "ClassReferencesSubclass" ) 109 @API( status = STABLE, since = "0.2.0" ) 110 public static ClassName from( final TypeElement element ) 111 { 112 final var retValue = ClassNameImpl.from( element ); 113 114 //---* Done *---------------------------------------------------------- 115 return retValue; 116 } // from() 117 118 /** 119 * Returns a class name created from the given parts.<br> 120 * <br>For example, calling this method with package name 121 * {@code "java.util"} and simple names {@code "Map"} and {@code "Entry"} 122 * yields {@code java.util.Map.Entry}. 123 * 124 * @param packageName The package name. 125 * @param simpleName The name of the top-level class. 126 * @param simpleNames The names of the nested classes, from outer to 127 * inner. 128 * @return The new {@code ClassName} instance. 129 */ 130 @SuppressWarnings( "ClassReferencesSubclass" ) 131 @API( status = STABLE, since = "0.2.0" ) 132 public static ClassName from( final CharSequence packageName, final CharSequence simpleName, final CharSequence... simpleNames ) 133 { 134 final var retValue = ClassNameImpl.from( packageName, simpleName, simpleNames ); 135 136 // ---* Done *---------------------------------------------------------- 137 return retValue; 138 } // from() 139 140 /** 141 * {@inheritDoc} 142 */ 143 @Override 144 public boolean isAnnotated(); 145 146 /** 147 * Returns a new instance for an implementation of {@code ClassName} for 148 * the specified {@code name} as nested inside this class. 149 * 150 * @param name The name for the new nested class. 151 * @return The new instance. 152 */ 153 public ClassName nestedClass( final CharSequence name ); 154 155 /** 156 * Returns the package name, like {@code java.util} for 157 * {@code java.util.Map.Entry}. Returns the empty String for the default 158 * package. 159 * 160 * @return The package name. 161 */ 162 public String packageName(); 163 164 /** 165 * Returns the enclosing class, like {@link Map} for 166 * {@code java.util.Map.Entry}. The return value will be 167 * {@linkplain Optional#empty() empty} 168 * if this class is not nested in another class. 169 * 170 * @return An instance of 171 * {@link Optional} 172 * that holds the name of the enclosing class. 173 */ 174 public Optional<ClassName> parentClass(); 175 176 /** 177 * Creates a class that shares the same enclosing package or class. 178 * 179 * @param name The name of the peer class to create. 180 * @return The new instance for the peer class. 181 */ 182 public ClassName peerClass( final CharSequence name ); 183 184 /** 185 * Returns the binary name of a class, as used by reflection. 186 * 187 * @return The binary name. 188 */ 189 public String reflectionName(); 190 191 /** 192 * Returns the simple name of this class, like {@code Entry} for 193 * {@code java.util.Map.Entry}. 194 * 195 * @return The simple name. 196 */ 197 public String simpleName(); 198 199 /** 200 * Returns a list of the simple names for this nesting group. 201 * 202 * @return The simple names. 203 */ 204 public List<String> simpleNames(); 205 206 /** 207 * Returns the top class in this nesting group. 208 * 209 * @return The name of the top level class. 210 */ 211 public ClassName topLevelClassName(); 212 213 /** 214 * Creates a new instance for an implementation of {@code ClassName} as a 215 * copy of this one, but without any annotations. 216 * 217 * @return The new instance. 218 */ 219 @Override 220 public ClassName withoutAnnotations(); 221} 222// interface ClassName 223 224/* 225 * End of File 226 */