Does getInstance() denote a singleton according the singleton pattern?

Question

Having worked with C# before, I have considered

Calendar cal = Calendar.getInstance();

to be a singleton method according the GoF Singleton pattern (Wikipedia) and I wondered how to create two calendars, since Dateis somewhat deprecated.

From the documentation

Gets a calendar using the default time zone and locale.

and the overloads

getInstance(TimeZone zone)
getInstance(Locale aLocale)

this seemed to me to be a generalization of the singleton pattern to create a singleton per time zone and locale. But I wanted two calendars in the same time zone.

However, when I conducted the test

@Test
public void test()
{
    Calendar cal = Calendar.getInstance();
    Calendar cal2 = Calendar.getInstance();
    assertTrue(cal == cal2); 
}

it failed, telling me that this getInstance() method is actually not a singleton pattern getInstance() method but something else.

So, does getInstance() in general denote a singleton according the singleton pattern in Java or not? If so, what are the key wordings in the Java documentation to find out it is or is not a singleton? If not, how do I identify a singleton pattern in Java? Or is Calendar the only exception?

I'd not like to implement a unit test each time I meet a getInstance() call.

I have read this answer to "What is an efficient way to implement a singleton pattern in Java?", which would work exactly like in C#, which contradicts the Calendar implementation.

Answer 1

Calendar is not a singleton, and each call to Calendar.getInstance(...) returns a different instance. The Javadoc doesn't say that each call will return the same instance, so you have no reason to assume that it will.

Calendar.getInstance(...) better fits the factory design pattern.

Looking at other examples of getInstance, such as Locale.getInstance(), you see that the Javadoc tells you if consecutive calls may return the same instance :

/**
 * Returns a <code>Locale</code> constructed from the given
 * <code>language</code>, <code>country</code> and
 * <code>variant</code>. If the same <code>Locale</code> instance
 * is available in the cache, then that instance is
 * returned. Otherwise, a new <code>Locale</code> instance is
 * created and cached.
 *
 * @param language lowercase two-letter ISO-639 code.
 * @param country uppercase two-letter ISO-3166 code.
 * @param variant vendor and browser specific code. See class description.
 * @return the <code>Locale</code> instance requested
 * @exception NullPointerException if any argument is null.
 */
static Locale getInstance(String language, String country, String variant)

Again, this is not a singleton, but the instances are cached, as the Javadoc says. Unless the Javadoc says so, you can expect each call to getInstance to return a different instance.

Answer 2

Method getInstance() usually denotes a singleton in java, but it is not a rule engraved in the rock. The only way to tell for sure it is a singleton, you must either look at the documentation (if any) or better, the implementation.