1//
2// Copyright (c) ZeroC, Inc. All rights reserved.
3//
4
5#pragma once
6
7[["cpp:dll-export:ICE_API"]]
8[["cpp:doxygen:include:Ice/Ice.h"]]
9[["cpp:header-ext:h"]]
10
11[["ice-prefix"]]
12
13[["js:module:ice"]]
14
15[["objc:dll-export:ICE_API"]]
16[["objc:header-dir:objc"]]
17
18[["python:pkgdir:Ice"]]
19
20#ifndef __SLICE2JAVA_COMPAT__
21[["java:package:com.zeroc"]]
22#endif
23
24["objc:prefix:ICE"]
25module Ice
26{
27
28#if !defined(__SLICE2PHP__)
29/**
30 *
31 * A factory for values. Value factories are used in several
32 * places, such as when Ice receives a class instance and
33 * when Freeze restores a persistent value. Value factories
34 * must be implemented by the application writer and registered
35 * with the communicator.
36 *
37 **/
38["delegate"]
39local interface ValueFactory
40{
41    /**
42     *
43     * Create a new value for a given value type. The type is the
44     * absolute Slice type id, i.e., the id relative to the
45     * unnamed top-level Slice module. For example, the absolute
46     * Slice type id for an interface <code>Bar</code> in the module
47     * <code>Foo</code> is <code>"::Foo::Bar"</code>.
48     *
49     * Note that the leading "<code>::</code>" is required.
50     *
51     * @param type The value type.
52     *
53     * @return The value created for the given type, or nil if the
54     * factory is unable to create the value.
55     *
56     **/
57    Value create(string type);
58}
59
60/**
61 *
62 * A value factory manager maintains a collection of value factories.
63 * An application can supply a custom implementation during communicator
64 * initialization, otherwise Ice provides a default implementation.
65 *
66 * @see ValueFactory
67 *
68 **/
69local interface ValueFactoryManager
70{
71    /**
72     *
73     * Add a value factory. Attempting to add a factory with an id for
74     * which a factory is already registered throws AlreadyRegisteredException.
75     *
76     * When unmarshaling an Ice value, the Ice run time reads the
77     * most-derived type id off the wire and attempts to create an
78     * instance of the type using a factory. If no instance is created,
79     * either because no factory was found, or because all factories
80     * returned nil, the behavior of the Ice run time depends on the
81     * format with which the value was marshaled:
82     *
83     * If the value uses the "sliced" format, Ice ascends the class
84     * hierarchy until it finds a type that is recognized by a factory,
85     * or it reaches the least-derived type. If no factory is found that
86     * can create an instance, the run time throws NoValueFactoryException.
87     *
88     * If the value uses the "compact" format, Ice immediately raises
89     * NoValueFactoryException.
90     *
91     * The following order is used to locate a factory for a type:
92     *
93     * <ol>
94     *
95     * <li>The Ice run-time looks for a factory registered
96     * specifically for the type.</li>
97     *
98     * <li>If no instance has been created, the Ice run-time looks
99     * for the default factory, which is registered with an empty type id.
100     * </li>
101     *
102     * <li>If no instance has been created by any of the preceding
103     * steps, the Ice run-time looks for a factory that may have been
104     * statically generated by the language mapping for non-abstract classes.
105     * </li>
106     *
107     * </ol>
108     *
109     * @param factory The factory to add.
110     *
111     * @param id The type id for which the factory can create instances, or
112     * an empty string for the default factory.
113     *
114     **/
115    void add(ValueFactory factory, ["objc:param:sliceId"] string id);
116
117    /**
118     *
119     * Find an value factory registered with this communicator.
120     *
121     * @param id The type id for which the factory can create instances,
122     * or an empty string for the default factory.
123     *
124     * @return The value factory, or null if no value factory was
125     * found for the given id.
126     *
127     **/
128    ["cpp:const", "cpp:noexcept"] ValueFactory find(string id);
129}
130#endif
131
132}
133