What is the meaning of Deprecated ? How and When To Deprecate APIs ..!

What "Deprecated" Means

You may have heard the term, "self-deprecating humor," or humor that minimizes the speaker's importance. A deprecated class or method is like that. It is no longer important. It is so unimportant, in fact, that you should no longer use it, since it has been superseded and may cease to exist in the future.

Java provides a way to express deprecation because, as a class evolves, its API (application programming interface) inevitably changes: methods are renamed for consistency, new and better methods are added, and fields change. But such changes introduce a problem. You need to keep the old API around until developers make the transition to the new one, but you don't want them to continue programming to the old API.

The ability to deprecate a class, method, or member field solves the problem. Java supports two mechanisms for deprecation: and an annotation, (supported starting with J2SE 5.0) and a Javadoc tag (supported since 1.1). Existing calls to the old API continue to work, but the annotation causes the compiler to issue a warning when it finds references to deprecated program elements. The Javadoc tag and associated comments warn users against using the deprecated item and tell them what to use instead.

When to Deprecate

When you design an API, carefully consider whether it supersedes an old API. If it does, and you wish to encourage developers (users of the API) to migrate to the new API, then deprecate the old API. Valid reasons to deprecate an API include:

• It is insecure, buggy, or highly inefficient
• It is going away in a future release
• It encourages bad coding practices

Deprecation is a reasonable choice in all these cases because it preserves "backward compatibility" while encouraging developers to change to the new API. Also, the deprecation comments help developers decide when to move to the new API, and so should briefly mention the technical reasons for deprecation.

It is not necessary to deprecate individual member fields (properties) of a deprecated class, unless of course you want to explain a specific point about a property.

How to Deprecate

Starting with J2SE 5.0, you deprecate a class, method, or field by using the @Deprecated annotation. Additionally, you can use the @deprecated Javadoc tag tell developers what to use instead.

Using the annotation causes the Java compiler to generate warnings when the deprecated class, method, or field is used. The compiler suppresses deprecation warnings if a deprecated compilation unit uses a deprecated class, method, or field. This enables you to build legacy APIs without generating warnings.

You are strongly recommended to use the Javadoc @deprecated tag with appropriate comments explaining how to use the new API. This ensures developers will have a workable migration path from the old API to the new API. For more information, see Using the @deprecated Javadoc Tag.

NOTE: The Java Language Specification requires compilers to issue warnings when classes, methods, or fields marked with the @Deprecated annotation are used. Compilers are not required by the Java Language Specification to issue warnings when classes, methods, or fields marked with the @deprecated Javadoc tag are accessed, although the Sun compilers currently do so. However, there is no guarantee that the Sun compiler will always issue such warnings.

Using the @Deprecated Annotation

J2SE 5.0 introduces a new language feature called annotations (also called metadata). One of the Java language's built-in annotations is the @Deprecated annotation. To use it, you simply precede the class, method, or member declaration with "@Deprecated."

Using the @Deprecated annotation to deprecate a class, method, or field ensures that all compilers will issue warnings when code uses that program element. In contrast, there is no guarantee that all compilers will always issue warnings based on the @deprecated Javadoc tag, though the Sun compilers currently do so. Other compilers may not issue such warnings. Thus, using the @Deprecated annotation to generate warnings is more portable that relying on the @deprecated Javadoc tag.

In addition, the @Deprecated annotation causes the javadoc-generated documentation to be marked "Deprecated" wherever that program element appears.

NOTE: Deprecation applies to classes and to individual methods or properties, not to their names. It is possible for a single method to have deprecated and non-deprecated overloadings. It is possible for a non-deprecated property to hide or override a deprecated one, which removes deprecation. As developer of an API, it is your responsibility to deprecate overrides of a deprecated method, if in fact they should be deprecated.

Example

The following is a simple example of using the @Deprecated annotation from java.lang.Thread:

public
class Thread implements Runnable {
...
@Deprecated
    public final void stop() {
  synchronized (this) {
...

Using the @deprecated Javadoc Tag

You can use the @deprecated tag to make Javadoc show a program element as deprecated. The @deprecated tag must be followed by a space or newline. In the paragraph following the @deprecated tag, explain why the item has been deprecated and suggest what to use instead.

Javadoc generates special HTML based on @deprecated tags: it moves the paragraph following the @deprecated tag to the front of the description, placing it in italics and preceding it with a warning, "Note: foo is deprecated", in bold. It also adds "Deprecated" in bold to any index entries mentioning the deprecated entity.

The tagged paragraph can be empty, but empty deprecation paragraphs are bad form, because they do not help the user fix the warnings that arise from the deprecation. Include paragraphs marked with @link or@see tags that refer to the new versions of the same functionality. It is usually not a good idea to mention a timetable for phase-out of the deprecated API; this is a business decision that is best communicated other ways.

For more information on using the @deprecated Javadoc tag, see Javadoc - The Java API Documentation Generator.

Example

The following examples show how to use the @deprecated Javadoc tag. They also illustrate the @Deprecated annotation, to emphasize that the two should be used together.

Here is an example of the most common form of a deprecated method (for Javadoc 1.2 and later):

/**
 * @deprecated  As of release 1.3, replaced by {@link #getPreferredSize()}
 */
@Deprecated public Dimension preferredSize() {
return getPreferredSize();
}

If the API reorganization was more than renaming, the deprecation may be more complex. Here is an example of a method that is being retracted:

/**
 * Delete multiple items from the list.
 *
 * @deprecated  Not for public use.
 *    This method is expected to be retained only as a package
 *    private method.  Replaced by
 *    {@link #remove(int)} and {@link #removeAll()}
 */
@Deprecated public synchronized void delItems(int start, int end) {
...
}

Difference between Java and J2EE

Core Java refers to the core or basic features of java like object orientation, inheritance, classes, objects, threads, etc. It is used to create simple java applications.

J2EE stands for Java 2 Enterprise Edition. It uses features like Servlets, JSPs, Struts, Hibernate etc which are all advanced J2EE concepts that are built on top of java.

Java is a object-oriented programming language which is platform neutral. That is unlike C or C++ java programs, Java can be run on any operating system with its JVM. J2EE is just a specification for server side programs. That is to support internet applications, distributed and uses component model. So that Enterprises use this server side technology in their distributed business. Since J2EE is just a server side specification, anybody can implement the specification but again using Java. Hence today we have Custom implemented J2EE servers from Oracle, SUN, IBM and so on..

Your First Java Program: Hello World

In this section, our plan is to lead you into the world of Java programming by taking you through the three basic steps required to get a simple program running. The Java system is a collection of applications not unlike any of the other applications that you are accustomed to using (such as your word processor, e-mail program, or internet browser). As with any application, you need to be sure that Java is properly installed on your computer. You also need an editor and a terminal application. Here are system specific instructions for three popular home operating systems. [ Mac OS X · Windows · Linux ]

Programming in Java.

 We break the process of programming in Java into three steps:

1. Create the program by typing it into a text editor and saving it to a file named, say, MyProgram.java.
2. Compile it by typing "javac MyProgram.java" in the terminal window.
3. Run (or execute) it by typing "java MyProgram" in the terminal window.

The first step creates the program; the second translates it into a language more suitable for machine execution (and puts the result in a file namedMyProgram.class); the third actually runs the program.

• Creating a Java program. A program is nothing more than a sequence of characters, like a sentence, a paragraph, or a poem. To create one, we need only define that sequence characters using a text editor in the same way as we do for e-mail. HelloWorld.java is an example program. Type these character into your text editor and save it into a file named HelloWorld.java.

  public class HelloWorld { public static void main(String[] args) { System.out.println("Hello, World"); } }

• Compiling a Java program. At first, it might seem to you as though the Java programming language is designed to be best understood by the computer. Actually, to the contrary, the language is designed to be best understood by the programmer (that's you). A compiler is an application that translates programs from the Java language to a language more suitable for executing on the computer. It takes a text file with the .java extension as input (your program) and produces a file with a .class extension (the computer-language version). To compile HelloWorld.java type the boldfaced text below at the terminal. (We use the % symbol to denote the command prompt, but it may appear different depending on your system.)

  % javac HelloWorld.java

  If you typed in the program correctly, you should see no error messages. Otherwise, go back and make sure you typed in the program exactly as it appears above.
• Executing a Java program. Once you compile your program, you can run it. This is the exciting part, where the computer follows your instructions. To run the HelloWorld program, type the following at the terminal:

  % java HelloWorld

  If all goes well, you should see the following response

  Hello, World

• Understanding a Java program. The key line with System.out.println() send the text "Hello, World". When we begin to write more complicated programs, we will discuss the meaning of public, class, main, String[], args, System.out, and so on.
• Creating your own Java program. For the time being, all of our programs will be just like HelloWorld.java, except with a different sequence of statements in main(). The easiest way to write such a program is to:
  • Copy HelloWorld.java into a new file whose name is the program name followed by .java.
  • Replace HelloWorld with the program name everywhere.
  • Replace the print statement by a sequence of statements.

Errors.

 Most errors are easily fixed by carefully examining the program as we create it, in just the same way as we fix spelling and grammatical errors when we type an e-mail message.

• Compile-time errors. These errors are caught by the system when we compile the program, because they prevent the compiler from doing the translation (so it issues an error message that tries to explain why).
• Run-time errors. These errors are caught by the system when we execute the program, because the program tries to peform an invalid operation (e.g., division by zero).
• Logical errors. These errors are (hopefully) caught by the programmer when we execute the program and it produces the wrong answer. Bugs are the bane of a programmer's existence. They can be subtle and very hard to find.

One of the very first skills that you will learn is to identify errors; one of the next will be to be sufficiently careful when coding to avoid many of them.

Input and output.

 Typically, we want to provide input to our programs: data that they can process to produce a result. The simplest way to provide input data is illustrated in UseArgument.java. Whenever this program is executed, it reads the command-line argument that you type after the program name and prints it back out to the terminal as part of the message.

% javac UseArgument.java % java UseArgument Alice Hi, Alice. How are you? % java UseArgument Bob Hi, Bob. How are you?

Q + A

Q. Why Java?

A. The programs that we are writing are very similar to their counterparts in several other languages, so our choice of language is not crucial. We use Java because it is widely available, embraces a full set of modern abstractions, and has a variety of automatic checks for mistakes in programs, so it is suitable for learning to program. There is no perfect language, and you certainly will be programming in other languages in the future.

Q. Do I really have to type in the programs in the book to try them out?

A. Everyone should type in HelloWorld.java, but you can find all of the code in this book (and much more) on this booksite.

Q. What are Java's rules regarding tabs, spaces and newline characters?

A. There are not many. Java compilers treat them all to be equivalent. For example, we could also write HelloWorld as follows:

public class HelloWorld { public static void main ( String [] args) { System.out.println("Hello World") ; } }

But we do normally adhere to spacing and indenting conventions when we write Java programs, just as we always indent paragraphs and lines consistently when we write prose or poetry.

Q. What are the rules regarding quotation marks?

A. Material inside quotation marks is an exception to the rule of the previous question: things within quotes are taken literally so that you can precisely specify what gets printed. If you put any number of successive spaces within the quotes, you get that number of spaces in the output. If you accidentally omit a quotation mark, the compiler may get very confused, because it needs that mark to distinguish between characters in the string and other parts of the program. To print a quotation mark, a newline, or a tab, use \", \n, or \t, respectively, within the quotation marks.

Q. What is the meaning of the words public, static and void?

A. These keywords specify certain properties of main() that you will learn about later in the book. For the moment, we just include these keywords in the code (because they are required) but do not refer to them in the text.

Q. What happens when you omit a brace or misspell one of the words, like public or static or main? A. It depends upon precisely what you do. Such errors are called syntax errors. Try it out and see.

Q. Can a program use more than one command-line argument?

A. Yes, you can put several, though we normally use only a few. You refer to the second one as args[1], the third one as args[2], and so forth. Note that we start counting from 0 in Java.

Q. What Java systems libraries and methods are available for me to use?

A. There are thousands of them, but we introduce them to you in a deliberate fashion in this book to avoid overwhelming you with choices.

Q. How should I format my code? How should I comment my code?

A. Programmers use coding guidelines to make programs easier to read, understand, and maintain. As you gain experience, you will develop a coding style, just as you develop style when writing prose. Appendix B provides some guidelines for formatting and commenting your code. We recommend returning to this appendix after you've written a few programs.

Q. What exactly is a .class file?

A. It's a binary file (sequence of 0s and 1s). If you are using Unix or OS X, you can examine its contents by typing od -x HelloWorld.class at the command prompt. This displays the results in hexadecimal (base 16). In deference to Java's name, the first word of every .class file is cafe.

Exercises

1. Write a program TenHelloWorlds.java that prints "Hello, World" ten times.
2. Describe what happens if, in HelloWorld.java, you omit
   1. public
   2. static
   3. void
   4. args
3. Describe what happens if, in HelloWorld.java, you misspell (by, say, omitting the second letter)
   1. public
   2. static
   3. void
   4. args
4. Describe what happens if you try to execute Hi.java with:
   1. java Hi
   2. java Hi @!&^%
   3. java Hi 1234
   4. java Hi.class Bob
   5. java Hi.java Bob
   6. java Hi Alice Bob
5. Modify UseArgument.java to make a program UseThree.java that takes three names and prints out a proper sentence with the names in the reverse of the order given, so that for example, "java UseThree Alice Bob Carol" gives "Hi Carol, Bob, and Alice.".