Developers: breaking changes forthcoming in 1.50.0

[chocolateboy]

Here is a short list of public API changes:

• HTTPServer.group is a private instance variable; previously it was a public static one
• PMS.registry type is SystemUtils, and not WinUtils. All the Windows-specific functionality stays in WinUtils, the generic (non-working) one is in SystemUtils
• DLNAResource.getChildren() is a List<DLNAResource> instead of ArrayList<DLNAResource>; similarly getDLNAResources(...)
• The deprecated DLNAResource.reset(int) method has been removed
• The private String helper functions from the DLNAResource classes have been moved to the static StringUtils class
• In DLNAResource, the media, media_audio, media_subtitle, updateId, noName and skipTranscode instance variables are now protected - they were public previously - and appropriate getters have been added. Subclasses can modify these values, but I doubt that outer access is really needed.
• In DLNAResource the 'notranscodefolder' instance variable has been removed, because it's a class wide constant; instead of this, there is a 'isTranscodeFolderAvailable' method; if an object type doesn't want to have a transcode folder, it should return false, as in VirtualVideoAction

[renszarv]

Thanks, for copying here

[renszarv]

... and one more thing :
- the stored DLNAResource.id field doesn't contain the whole ID path - for example 0$1$5$3 - just the last part of it, in this case, only '3'. And if the addChildInternal method is used to add to the internal list of children, then this field is automaticaly populated, with ensuring that every child id is different. Here can you check, that how it's simplify things. Even better, the refreshChildren method is improved, split into two part: one is 'isRefreshNeeded()' which should check that is the underlyer objects changed, so refresh is needed, and into the 'refreshChildren()' method, which only role is to re-load the children objects. With these infrastructure, there is no need to restart ps3mediaserver to notice file system changes (Except for changing the root paths ... )

[renszarv]

... so a couple of new changes ...

• RendererConfiguration doesn't contains the IP address, and the 'network speed' for that client. Now, it's just a couple of settings for a device type. The IP address -> configuration stored in a HashMap, so it is still possible to get a renderer configuration for a given IP address. The network speed measurement is separated into net.pms.network.SpeedStats class
• The DLNAResource.getInputStream method signature is changed, now it accepts a Range parameter, instead of the couple of ints. This is because the Range can be a Range.Byte and a Range.Time, it depends on, what the client sends, a time range, or a byte range.
• A couple of methods in the HTTPResource class, which were previously instance methods, moved to static methods. Because they are plain utility code, there is no sense overriding them.
• To fix the automatic reloading of the nodes, the DLNAResource.refreshChildren method is separated to two independent steps: The implementation of the boolean isRefreshNeeded() should return true, if the underlying structure is changed. It should be a fast method, which will called every time, when the tree is browsed. The void refreshChildren can be slower, this will called only when isRefreshNeeded declared that there was changes.

[SharkHunter]

Changeing this DLNAResource.getInputStream is BAD REALLY BAD since basically every plugin developed overrides this method. Ever heard of backwards compatibility? The speed of changes now is too rapid there is no way to keep up and the current output in terms of actual new functionality is low. If you feel an urge to change/remove a method based on cosmetics do so BUT keep the old one in parallel for at least 2-3 releases so everybody get a chance to adapt.

[renszarv]

Changeing this DLNAResource.getInputStream is BAD REALLY BAD since basically every plugin developed overrides this method. Ever heard of backwards compatibility? The speed of changes now is too rapid there is no way to keep up and the current output in terms of actual new functionality is low. If you feel an urge to change/remove a method based on cosmetics do so BUT keep the old one in parallel for at least 2-3 releases so everybody get a chance to adapt.

Sorry, about breaking others code. If there were an easy way fixing the plugins - for example if there were hosted in the same svn/git repo - and we declare that, which plugins is essential, and needs to be in an always compiling state, then I would be the happiest.
For me, that the seeking works is a pretty big feature, I can understand, that for your devices, it doesn't changed anything.

[SharkHunter]

I have no problem with changes that fixes bugs thats good but you can do the change in two ways. The way where you change an previously exposed interface or where you keep that interface and make a new interface for the fix. I always try to make my changes backwards compatible (in my case it is probably not that important since I'm the only user of my interfaces) but for PMS core functions this is absolutely crucial. Since the code is written in Java it is also so easy to do this. Just keep the old function and let it call the new one. I don't see the reason for just removing all functions just "for the fun of it". If a public function needs to be changed (especially in real core classes like DLNAResource or VirtualFolder which are the most used classes by plugins) I would for on leave the old signature there for at least 2-3 releases before removing it. NOte that PMS.debug etc. are deprecated but not removed yet.

[renszarv]

I have no problem with changes that fixes bugs thats good but you can do the change in two ways. The way where you change an previously exposed interface or where you keep that interface and make a new interface for the fix. I always try to make my changes backwards compatible (in my case it is probably not that important since I'm the only user of my interfaces) but for PMS core functions this is absolutely crucial. Since the code is written in Java it is also so easy to do this. Just keep the old function and let it call the new one. I don't see the reason for just removing all functions just "for the fun of it". If a public function needs to be changed (especially in real core classes like DLNAResource or VirtualFolder which are the most used classes by plugins) I would for on leave the old signature there for at least 2-3 releases before removing it. NOte that PMS.debug etc. are deprecated but not removed yet.

Ok, I will modify the code for something like this:

Code: Select all

 @Deprecated
 public InputStream getInputStream(long a, long b, long c, RendererConfiguration x)  {
    return null;
 }

 public InputStream getInputStream(Range range, RendererConfiguration x)  {
   InputStream backCompat = getInputStream( /* something */, /* something */, /* something */, x);
   if (backCompat != null) { 
     return backCompat;
   }
   ....
 }


So the new code will call the old code, and if it's overriden by plugins, it will get a chance to do something, but the core codebase won't call this explicitly.
Is it good for you ?

[Raptor399]

I would rather do something like:

Code: Select all

/**
 * @deprecated Use getInputStream(Range range, RendererConfiguration x) instead.
 */
@Deprecated
public InputStream getInputStream(long a, long b, long c, RendererConfiguration x)  {
    // Convert args to Range
    Range range = oldToNew(a, b, c);

    // Call the new method
    return getInputStream(range, x);
}

/**
 * @since 1.50.0
 */
public InputStream getInputStream(Range range, RendererConfiguration x)  {
   // Same as it is now
}


In other words: leave the new code intact, and create a backwards compatible method that calls the new method.

[renszarv]

I would rather do something like:

Code: Select all

/**
 * @deprecated Use getInputStream(Range range, RendererConfiguration x) instead.
 */
@Deprecated
public InputStream getInputStream(long a, long b, long c, RendererConfiguration x)  {
    // Convert args to Range
    Range range = oldToNew(a, b, c);

    // Call the new method
    return getInputStream(range, x);
}

/**
 * @since 1.50.0
 */
public InputStream getInputStream(Range range, RendererConfiguration x)  {
   // Same as it is now
}


In other words: leave the new code intact, and create a backwards compatible method that calls the new method.

Unfortunately it's not possible, because we can get more information with the new method, because the old one haven't received the end of the time range, so we can call the old one, from the new, but not the otherwise.